Authentication

How Lunar API bearer tokens work: the Bearer prefix, token rotation on login, and revocation.

Authentication#

Every protected route expects a bearer token in the Authorization header:

Authorization: Bearer <accessToken>

Getting a token#

Tokens come from two endpoints:

• POST /auth/register — create a new user-role account.
• POST /auth/login — authenticate an existing account.

Both return the token with the literal Bearer prefix already attached:

{
  "user": { "id": "user_id", "username": "winter_fe", "role": "user", "banned": false },
  "accessToken": "Bearer eyJhbGciOi..."
}

Token rotation and revocation#

Lunar API stores a hash of the current token per user. Logging in or registering rotates that hash, which means:

• Each successful login or register invalidates the previous token for that user.
• A user has exactly one valid token at a time.

Requests made with a stale token fail the accessTokenHash check and return:

{ "status": 401, "message": "Invalid or revoked access token" }

When auth fails#

See Roles & permissions for what each role can reach, and Error shapes for the full list of envelopes.