Getting started

Authentication

Every request to the API is authenticated with an API key, which you send in the Authorization header.

API keys

API keys give access to your organization's sessions, jobs and files. We issue them to you, and each one starts with nm_sk_. A key is shown only once, so store it somewhere safe when you receive it, and if you lose one we'll issue you a new one. Treat your keys like passwords and keep them out of source code and logs.

Sending the key

Send the key as a bearer token, Authorization: Bearer <key>. To test a key, call GET /v1/presets as below. Like every sample on these pages, it reads the key from the NOMONO_API_KEY environment variable:

curl "https://platform-api.nomono.co/v1/presets" \  -H "Authorization: Bearer $NOMONO_API_KEY"

The MCP server takes the same header, as described in MCP.

Scopes

Every route except GET /v1/presets needs a scope, and keys have both jobs:write and outputs:read unless they were issued with other scopes.

Scope	Routes
`jobs:write`	`POST /v1/uploadsPOST /v1/uploads/{upload_id}/partsPOST /v1/uploads/{upload_id}/completeDELETE /v1/uploads/{upload_id}GET /v1/sources/{source_id}DELETE /v1/sources/{source_id}POST /v1/sessionsGET /v1/sessionsGET /v1/sessions/{session_id}DELETE /v1/sessions/{session_id}POST /v1/jobsDELETE /v1/jobs/{job_id}`
`outputs:read`	`GET /v1/jobsGET /v1/jobs/{job_id}GET /v1/jobs/{job_id}/outputsGET /v1/usage`
Any valid key	`GET /v1/presets`

Note

To read a session or a source, a key needs jobs:write.

If a key lacks the scope a route needs, the request gets a 403 that names it:

403 Forbidden

{  "error": {    "code": "forbidden",    "message": "API key does not have the required scopes",    "details": {      "required_scopes": ["outputs:read"]    }  }}

Expiry and revocation

Keys can be issued with an expiry date, and we can also revoke a key. When you rotate a key, start using the new one before the old one stops working.

Authentication errors

Every 401 has the code unauthorized and a WWW-Authenticate: Bearer header, and its message tells you what went wrong:

401 Unauthorized

{  "error": {    "code": "unauthorized",    "message": "Missing API key",    "hint": "Send the key in the Authorization header as Bearer <key>"  }}

Message	What to do
Missing API key	Send `Authorization: Bearer <key>`.
API key is not valid	Check the key for typos.
API key was revoked	Use another key, or ask us for a new one.
API key has expired	Use another key, or ask us for a new one.

All errors share the format described in Errors.