Developers

Authentication

How to authenticate a request to the Chronicler API. Send a bearer token on every call, get one by logging in or from a provider, and refresh it before it expires.

Every call to the Chronicler API carries a bearer token in the Authorization header. The server verifies it in middleware and puts the caller's identity, the principal, on the request. A request without a valid token is rejected before it reaches any handler.

Authorization: Bearer <access-token>

Two ways to hold a token

A person's browser session and a machine integration authenticate the same way at the header, but they get their tokens differently. This page covers user tokens. For a non-human integration, use a service account and an API token.

Get a token by logging in

A password login returns a token pair: a short-lived access token and a longer-lived refresh token. Send the access token on API calls. Keep the refresh token to get a new access token when the old one expires.

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "you@example.com", "password": "..." }

{
  "accessToken": "...",
  "refreshToken": "...",
  "expiresIn": 900
}

The tokens come back in the response body, not in a cookie. Store them where your client can read them and attach the access token to each request.

For provider login, such as Google, the flow is an OAuth Authorization Code exchange with PKCE. Because the provider returns the user through a browser navigation and Chronicler issues tokens in a body rather than a cookie, the callback hands your app a single-use handoff code. Your app trades that code for the real token pair. The token never travels in the callback URL.

Refresh before you expire

An access token is deliberately short-lived. When it is close to expiry, exchange the refresh token for a new pair:

POST /api/v1/auth/refresh
Content-Type: application/json

{ "refreshToken": "..." }

Each refresh issues a new pair and retires the old refresh token. If a refresh token is ever replayed, Chronicler detects it and rejects it, which is a signal the token was leaked.

Sessions are revocable

A session can be ended at once, not just left to expire. A user can list their active sessions and revoke any of them, and a revoked session's tokens stop working immediately through a per-family liveness check. This is what makes "sign out everywhere" real rather than cosmetic.

Step-up for dangerous actions

Some actions demand fresh proof that you are still at the keyboard, not just that you logged in earlier. Changing multi-factor settings, changing billing, and starting an impersonation session all sit behind step-up authorisation: a recent re-proof of identity, recorded server-side. If a call needs step-up and you have not re-proved recently, the API tells you, and you re-authenticate before retrying.

Where to go next