JWT authentication

Pass a Bearer token in the Authorization header to authenticate requests to protected endpoints.

After logging in with Basic Auth, Userverse returns a JWT access token. You include this token in the Authorization header of every request to a protected endpoint.

Passing the token

Set the Authorization header to Bearer <access_token>:

Authorization: Bearer <your-access-token>

A complete curl example:

curl -X GET http://localhost:8501/user/get \
  -H "Authorization: Bearer <your-access-token>"

The header value must start with Bearer (with a space). Any other prefix, or an absent header, returns a 401 Unauthorized error.

Token response model

When you log in, Userverse returns the following token response inside a data envelope:

token_type · string · required

Always "bearer". Use this value to confirm the token scheme before storing the token.

access_token · string · required

A signed JWT to include in the Authorization: Bearer header for protected endpoint calls. Expires at access_token_expiration.

access_token_expiration · string · required

UTC timestamp when the access token expires, formatted as YYYY-MM-DD HH:MM:SS. Controlled by jwt.TIMEOUT in your config (default: 30 minutes).

refresh_token · string · required

A signed JWT you can use to obtain a new token pair without logging in again. Expires at refresh_token_expiration.

refresh_token_expiration · string · required

UTC timestamp when the refresh token expires, formatted as YYYY-MM-DD HH:MM:SS. Controlled by jwt.REFRESH_TIMEOUT in your config (default: 60 minutes).

Example response:

{
  "message": "User logged in successfully",
  "data": {
    "token_type": "bearer",
    "access_token": "<your-access-token>",
    "access_token_expiration": "2026-04-01 10:30:00",
    "refresh_token": "<your-refresh-token>",
    "refresh_token_expiration": "2026-04-01 11:00:00"
  }
}

Configuration

JWT behaviour is controlled by the jwt block in your config.json:

{
  "jwt": {
    "SECRET": "your_jwt_secret",
    "ALGORITHM": "HS256",
    "TIMEOUT": 30,
    "REFRESH_TIMEOUT": 60
  }
}

Key	Description	Default
SECRET	Secret key used to sign and verify tokens. Set a long, random value in production.	"secret1234"
ALGORITHM	Signing algorithm. Userverse uses "HS256".	"HS256"
TIMEOUT	Access token lifetime in minutes.	30
REFRESH_TIMEOUT	Refresh token lifetime in minutes.	60

Never use the default SECRET value in production. Generate a strong random secret and store it outside your repository.

Token type enforcement

Every JWT issued by Userverse contains a type claim in its payload. The server validates this claim on every request:

• All protected endpoints require "type": "access". Sending a refresh token to a protected endpoint returns 403 Forbidden.

This prevents accidental or malicious use of a refresh token in place of an access token. When your access token expires, re-authenticate via PATCH /user/login to obtain a new token pair.

Common errors

Status	Message	Cause
401 Unauthorized	"Invalid request"	Missing Authorization header or header is not in Bearer <token> format
401 Unauthorized	"Token has expired"	The access token has passed its expiration time
401 Unauthorized	"Invalid token"	The JWT signature is invalid or the token is malformed
403 Forbidden	"Invalid token for access token"	A refresh token was submitted to an access-token-protected endpoint (wrong token type)
403 Forbidden	"Missing user data in token"	The token payload does not contain a user claim

A 401 on a protected endpoint typically means the token is missing or expired. Re-authenticate via PATCH /user/login to obtain a new pair. A 403 means the token was parseable but was rejected for a structural reason — check that you are sending the access token, not the refresh token.

Next steps

Basic Auth

Learn how to obtain a token by logging in with HTTP Basic Auth.

API reference

See the full list of authentication endpoints with request and response schemas.