KERN API authentication with JWT Bearer tokens

The KERN API uses JWT (JSON Web Token) Bearer authentication for all protected endpoints. Tokens are signed with HS256 and expire after 30 minutes. There is no refresh-token mechanism — call POST /login again to obtain a new token.

Obtaining a token

There are two ways to get an access token:

Method	Endpoint	When to use
Register	`POST /register`	New user — creates an account and returns a token immediately
Login	`POST /login`	Existing user — authenticates with email and password

Both endpoints return the same LoginResponse shape.

LoginResponse shape

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "username": "jaime",
    "email": "jaime@example.com",
    "full_name": "Jaime Gayo",
    "phone": null,
    "avatar_url": null,
    "role": "user",
    "bio": null,
    "has_completed_quiz": false,
    "assigned_routine": null,
    "created_at": "2026-05-14T10:00:00+00:00",
    "disabled": false
  }
}

The JSON key is accessToken (camelCase), not access_token. This is an intentional alias defined in the Pydantic model using Field(..., alias="accessToken").

Using the token

Include the token in the Authorization header of every authenticated request:

Authorization: Bearer <accessToken>

curl --request GET \
  --url https://kern-api.vercel.app/users/me \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token expiry and renewal

Tokens expire 30 minutes after they are issued. There is no silent refresh. When a token expires:

The API returns 401 Unauthorized.
The client must call POST /login with the user’s email and password to obtain a fresh token.
Store the new accessToken and continue making requests.

Special case — username update

PUT /users/update_name returns a full LoginResponse (including a new JWT token) because the username is embedded in the token payload (sub claim). After updating the username, replace the stored token with the new one to avoid immediate 401 errors.

Error responses

detail

string

Human-readable error message.

Status	`detail` value	Cause
`401`	`"No se pudo validar el token de acceso"`	Token is missing, malformed, or expired
`401`	`"Email o contraseña incorrectos"`	Wrong credentials on login
`400`	`"Usuario inactivo"`	Account has been disabled

{
  "detail": "No se pudo validar el token de acceso"
}

CORS

The API allows all origins (*) and all HTTP methods, so tokens can be used from any client including web browsers and Android apps.

Overview

Endpoints

Data Models

KERN API authentication with JWT Bearer tokens

Obtaining a token

LoginResponse shape

Using the token

Token expiry and renewal

Special case — username update

Error responses

CORS

Build docs developers (and LLMs) love

Overview

Endpoints

Data Models

Documentation Index

​Obtaining a token

​LoginResponse shape

​Using the token

​Token expiry and renewal

​Special case — username update

​Error responses

​CORS

Build docs developers (and LLMs) love

Obtaining a token

LoginResponse shape

Using the token

Token expiry and renewal

Special case — username update

Error responses

CORS