Project Auth overview
Project auth is Noma’s built-in layer for your product’s end users—people who sign up and sign in inside the app you build. It is separate from how you (the developer) call the Content API.
How this differs from Content API keys
| Content API | Project auth | |
|---|---|---|
| Who | Your user account in the Noma app (developers, editors, automation) | End users of your project (customers, members, app users) |
| Credential | A personal access token from User Settings → API Keys (create it with the target workspace selected in the sidebar; each key is scoped to that workspace) | Session access and refresh tokens from sign-up / sign-in |
| Purpose | Read and write collections, entries, assets, webhooks, and project settings (according to token abilities) within that workspace | Sign-up, sign-in, profile, sessions, and user-owned API keys scoped to one project |
Content API requests use Authorization: Bearer <personal access token> plus the project-id header, as described in Authentication.
Project auth uses the same base URL and project-id header, but the bearer token on auth routes is either absent (sign-up, login, refresh) or a project user access token (JWT) for routes such as GET /auth/me.
End-user tokens do not replace Content API keys
An end-user access token identifies a signed-in project user. It is not a substitute for a personal access token when calling Content API routes (collections, entries, assets, and so on). Those routes require a token from your user account with the right abilities. The JavaScript SDK sends your personal access token for CMS routes and the project user token only for /auth/* calls, as configured in Installation & Setup.
Base URL and headers
https://app.nomacms.com/apiEvery request must include:
| Header | Required | Description |
|---|---|---|
project-id | Yes | Your project’s UUID. Auth is isolated per project: the same email in two projects is two different accounts. |
Authorization | Depends on route | Bearer token when the route requires an authenticated project user. Omitted for public auth actions (see below). |
Accept | Recommended | application/json |
Auth routes at a glance
Routes are under /auth/ relative to the API base (for example POST /api/auth/login when using the full URL https://app.nomacms.com/api/auth/login).
| Method | Path | Auth on request |
|---|---|---|
POST | /auth/signup | None |
POST | /auth/login | None |
POST | /auth/login/social | None |
POST | /auth/refresh | None (body carries refresh_token) |
POST | /auth/verify-email/resend | None |
POST | /auth/verify-email/confirm | None |
GET | /auth/me | Project user access token |
POST | /auth/logout | Project user access token |
POST | /auth/logout-all | Project user access token |
POST | /auth/change-password | Project user access token |
GET | /auth/api-keys | Project user access token |
POST | /auth/api-keys | Project user access token |
POST | /auth/api-keys/{id}/revoke | Project user access token |
Successful sign-in, sign-up (when tokens are issued immediately), and refresh return JSON with access_token, token_type (Bearer), expires_at, optional refresh_token and refresh_token_expires_at, and a user object. See Sign Up & Sign In and Session Management.
Email verification
Depending on project settings, new accounts may need email verification before they receive session tokens, or before they can sign in. The API returns structured payloads (verification_required, verification_token, code) so your app can drive its own email or deep-link flow. Details are covered in Sign Up & Sign In.
Rate limiting
Sign-up, sign-in, social sign-in, refresh, verification, and user API key routes are rate limited per IP and project. If you hit a limit, responses use 429 with a retry_after or cooldown fields where applicable.
JavaScript SDK
Configure createClient with projectId, optionally apiKey for Content API calls, and projectUserAuth for persisted end-user tokens. Auth methods (signUp, signInWithPassword, signInWithSocial, refreshSession, signOut, me, and others) use the same client.
Next steps
- Sign Up & Sign In — Password flows and verification.
- Social Login — Exchanging provider
id_tokenvalues. - Session Management — Refresh, logout, and profile.
- User API Keys — Per-user keys (
uak_prefix) and how they relate to the Content API.