API keys vs. user access tokens
Server-to-server traffic uses API keys (see Authentication). Logging a user in from your app issues a short-lived access token (JWT) plus a refresh token.
Logging in
POST /api/v1/auth/user/login
{
"email": "alice@example.com",
"password": "..."
}
→ 200
{
"data": {
"access_token": "eyJhbGc…",
"refresh_token": "eyJhbGc…",
"principal": { "id": "...", "role": "user", ... }
}
}Refreshing
Access tokens expire after 15 minutes. When you get a 401 with "code": "TOKEN_EXPIRED", call /api/v1/auth/{role}/refresh with the refresh token to get a new pair. Refresh tokens rotate on every use, so always store the latest one.
POST /api/v1/auth/user/refresh
{ "refresh_token": "eyJhbGc…" }Logout
POST /api/v1/auth/{role}/logout invalidates the refresh token server-side; the access token continues to work until its expiry. For an immediate kill switch, revoke the device under /auth/{role}/me/devices.