Authentication

The Nucleus API uses bearer tokens for automation, and session cookies for the operator portal. This page covers tokens — the only path you should script against.

Minting a token

Tokens are minted from the operator portal, not the API. There's no programmatic way to create a token without an existing session — that's deliberate, so a leaked token can't propagate itself.

1. Sign in to your operator portal.
2. Open the user menu → API tokens.
3. Click New token, give it a name and pick a scope.
4. Copy the plaintext immediately. It's shown once and never readable again.

Programmatically, the same operation is POST /api/auth/tokens — but the request must come over a session cookie, not a bearer token. See the token endpoints.

Sending a token

Set the Authorization header:

Authorization: Bearer nuc_a1b2c3d4...

Tokens are opaque — don't try to parse them. The server-side hash is what actually authenticates; the prefix you see (nuc_…) is for human readability and audit trails only.

Scopes

Three scopes, narrowing the permissions a token grants:

Scope	Allows
cli	The full surface a hub admin can touch — provisioning, lifecycle actions, federation patches
provisioning	Create and destroy spokes; can't change federation-wide config
readonly	All GET endpoints; no writes

Endpoints that require a specific scope are tagged in the reference. Hitting a scope you don't have returns 403.

Rotation

Tokens don't expire by default — set expiresAt on the create payload if you want them to. There's no automatic rotation; rotate yours on whatever cadence your security policy requires.

To rotate:

1. Mint a new token.
2. Update your automation to use it.
3. Revoke the old one with DELETE /api/auth/tokens/:id.

The old token keeps working until the DELETE returns; there's no grace period, so don't revoke until step 2 is verified.

Inspecting the current caller

GET /api/auth/me returns the user record associated with the bearer token (or session). Useful for sanity-checking which token a CI pipeline is actually using:

curl -H "Authorization: Bearer $NUCLEUS_TOKEN" \
  https://app.nucleuslms.io/api/auth/me

{
  "user": {
    "id": "...",
    "email": "ops@your-domain",
    "role": "hub_admin",
    "federationIds": ["fed_1234"]
  }
}

What sessions can do that tokens can't

A handful of endpoints are session-only:

• Minting tokens (POST /auth/tokens)
• Onboarding wizard completion
• Anything in the password-reset / invite / signup / verify-email flows

Bearer tokens hitting these endpoints get 401 token minting requires a session (or similar). That's by design — see Errors.