Authentication
Content API requests need a project id and a bearer token that identifies your user account.
Base URL:
https://app.nomacms.com/apiRequired headers
| Header | Required | Description |
|---|---|---|
project-id | Yes | Project UUID. Omitting it returns 400 (Project header missing.). An unknown UUID returns 404 (Project not found.). A 400 may also occur when the server cannot resolve workspace context from the token and header together. |
Authorization | Yes | Bearer token from User Settings → API Keys. Described in the next section. |
Bearer token (API key)
Create a token under User Settings → API Keys while the correct workspace is selected in the sidebar (the workspace switcher). Send it as:
Authorization: Bearer <token>The token is a personal access token for your user. It is scoped to the workspace that was active when you created the key. Abilities (read, create, and so on) apply to the token itself.
The project-id header selects which project this request targets. That project must live in the same workspace as the key. Use a different key for each workspace you integrate with (switch workspace in the dashboard, then create another key). Trying to use a key against a project in another workspace returns 404 (Project not found.) or 403 when billing or access checks apply.
Abilities
Each personal access token has one or more abilities. The API checks that the token allows the ability required for that route (or * for full access).
| Ability | Typical use |
|---|---|
read | Read project metadata, list/get collections, list/get entries, list/get assets |
create | Create entries, upload assets, bulk create |
update | Update entries, patch asset metadata, link translations, bulk update |
delete | Delete entries, delete assets, bulk delete |
admin | Create/update/delete collections and fields, webhooks, project locales, reorder |
If the token is valid but cannot perform the action, the API responds with 403 with body Forbidden.
Errors (common)
| Status | Meaning |
|---|---|
| 400 | Missing project-id |
| 401 | Missing or invalid bearer token |
| 403 | Authenticated but the token lacks the required ability |
| 404 | No project with that UUID |
Rate limiting
API routes apply Laravel rate limiting (for example 60 requests per minute on the default API group). Auth-heavy routes may use separate named limits. Expect 429 when throttled.
Related
- Get Project - Minimal request to verify headers and
read - List Collections - List collections with field definitions
- Create a Field - Add a field (
admin) - JavaScript SDK - Sends
project-idandAuthorizationfor you