Session Management
After sign-in, Noma issues a JWT access token and usually a refresh token. Access tokens expire; refresh tokens rotate according to server policy. Defaults are configured on the server (typical access TTL on the order of minutes, refresh TTL on the order of days).
All authenticated routes below require:
project-id: <your-project-uuid>
Authorization: Bearer <access_token>
Accept: application/jsonRefresh session
POST /api/auth/refreshBody
| Field | Type | Required |
|---|---|---|
refresh_token | string | Yes (min length 40) |
Responses
200 OK — New access_token, expires_at, and typically a rotated refresh_token with updated refresh_token_expires_at, plus user.
401 — Invalid refresh token. (revoked, expired, or wrong project).
403 — Email verification may block refresh until the account is verified; response may include verification_token.
This route does not send Authorization; only project-id and the JSON body.
Current user
GET /api/auth/me200 OK — { "user": { ... } } with id, uuid, email, display_name, email_verified_at, metadata.
401 — Missing or invalid access token.
Change password
POST /api/auth/change-passwordBody
| Field | Type | Required |
|---|---|---|
current_password | string | Yes |
new_password | string | Yes (min 8, max 255, must differ from current) |
200 OK — Password updated.
401 — Not authenticated.
422 — Current password incorrect or validation failed.
Logout (current session)
POST /api/auth/logoutRevokes the current session server-side. Send the access token for that session.
200 OK — Logged out.
Logout (all sessions)
POST /api/auth/logout-allRevokes all refresh sessions for the user in this project.
200 OK — Logged out from all sessions.
JavaScript SDK
| Method | Maps to |
|---|---|
refreshSession() | POST /auth/refresh |
me() | GET /auth/me |
changePassword({ current_password, new_password }) | POST /auth/change-password |
signOut() | POST /auth/logout |
signOutAll() | POST /auth/logout-all |
With projectUserAuth.autoRefresh left at default (true), the SDK retries once after refreshing when a project-user request returns 401, for methods that allow refresh.
import { createClient } from "@nomacms/js-sdk"
const noma = createClient({
projectId: process.env.NOMA_PROJECT_ID!,
projectUserAuth: {
accessToken: storedAccess,
refreshToken: storedRefresh,
autoRefresh: true,
},
})
const profile = await noma.me()onAuthStateChange notifies you on signed_in, token_refreshed, signed_out, and auth_error.
Related
- Overview — Which routes need which token.
- User API Keys — Long-lived keys for integrations (separate from refresh tokens).