Authentication

Every route except GET /v1/health requires an API key in the request header. There is no session, no cookie and no token exchange: one long-lived key, presented on every call.

Keys are created and revoked through the API keys endpoints. Rate limits apply per key rather than per account, so a runaway batch job cannot starve a production integration.

The header

Pass the key as a bearer token in the Authorization header:

Authorization: Bearer nk_live_8xQ2...

The Anthropic-compatible routes also accept Anthropic's native header, so an unmodified Anthropic SDK works with only a base URL change:

x-api-key: nk_live_8xQ2...

If both headers are present, Authorization wins.

Never pass the key in a query string: it lands in access logs and browser history. Headers do not.

Keys

Key secrets are prefixed by environment: nk_live_ keys hit production, nk_test_ keys run against a shared sandbox pool.

The secret is returned once, in the response to Create an API key, and is never retrievable afterwards. Store it in a secrets manager at creation time; losing it means issuing a new key.

A key can be bound to a project, in which case it sees only that project's files, runs and checkpoints. Use project-bound keys to keep one team's workloads invisible to another's, even inside the same account.

Scopes

Every endpoint in the API reference declares the scope it needs, and a key carries one or more. Grant each integration the narrowest set that covers its calls.

Rotating a key

Rotation never requires downtime, because two keys can be valid at once:

1. Create the replacement key with the same scopes and project binding.
2. Cut traffic over to the new key and confirm the old one has gone quiet.
3. Revoke the old key.

Both keys stay valid between steps 1 and 3, so roll the new secret out to your deployments at whatever pace your release process allows.

Failure modes

A 401 means the key itself was rejected: missing, malformed, revoked or unknown.

{
  "error": {
    "type": "authentication_error",
    "message": "No API key provided. Pass Authorization: Bearer <key>."
  }
}

A 403 means the key is valid but not permitted: it lacks the scope the route requires, or it is bound to a different project than the resource. The response names the missing scope:

{
  "error": {
    "type": "permission_error",
    "required_scope": "train",
    "message": "Key key_2Fd has scopes [read, infer]."
  }
}

Verifying a key

GET /v1/auth/verify checks the presented key without side effects and returns its ID, scopes and project binding. It accepts any valid key regardless of scope, which makes it the first call to make when an integration returns 403 and nobody is sure which key the deployment is actually presenting. See Verify the current key for the full reference.

curl https://api.nucleus-ai.io/v1/auth/verify \
  -H "Authorization: Bearer $NUCLEUS_API_KEY"

{
  "key_id": "key_2Fd",
  "name": "production-backend",
  "prefix": "nk_live_8x",
  "scopes": ["read", "infer"],
  "project_id": "proj_acme",
  "expires_at": null
}

If the scopes or project_id in the response are not what you expected, the deployment is holding the wrong key. Rotate in the correct one rather than widening the scopes of the key you found.