Tokens

Bearer JWTs, audiences, and how to mint org-scoped tokens for programmatic access.

Norcube's APIs accept Bearer JWT tokens. The dashboard and the LangSync CLI handle token lifecycle for you; this page is for custom integrations.

Token shape

Tokens are signed JWTs with claims for the user, the organization, the audience (which service the token is valid against), and a token type marker. Pass tokens in the Authorization header:

Authorization: Bearer <jwt>

Access tokens are short-lived; refresh tokens last longer. Exact lifetimes are subject to change – your client should always be ready to handle 401 INVALID_TOKEN by refreshing and retrying once.

Audiences

Each Norcube product validates tokens against its own audience. A token minted for one product won't authenticate against another. Audiences in use:

auth – for the auth service itself (listing organizations, user info).
langsync-api – LangSync.
snapdb-api – Backup.
domainradar – DomainRadar.
billing – billing service.

When you mint a token (see below), you choose the audience.

Mint an org-scoped token

For a custom integration calling Norcube APIs, you can exchange a refresh token for an access token scoped to a specific org and audience via the auth service's OAuth2 endpoint:

POST /oauth/token  (on the auth service host)

grant_type=refresh_token
refresh_token=<your-refresh-token>
audience=<service-name>          # e.g. langsync-api
organization_id=<org-uuid>

The response contains a fresh access token and (optionally) a new refresh token. Cache the access token until close to its expiry, then refresh.

The auth service host is exposed via the PUBLIC_AUTH_SERVICE_BACKEND environment variable in the JDS dashboard repo. Your client's API key tooling, when available, is the preferred path; see below.

For SaaS-style API access

When your application needs to call Norcube APIs at runtime (not your user), the cleanest credential today is an API key rather than a refresh-token loop:

LangSync has API keys. See LangSync → Manage API keys.
Backup, DomainRadar, PromptHub don't yet have API keys. Use a service-account user with a stored refresh token and the OAuth2 flow above.

Cross-product API keys are on the roadmap.

Behaviour and edge cases

Expired access tokens return 401 INVALID_TOKEN. The right response is to refresh once and retry.
Wrong audience returns 401. Mint a token with the correct audience for the API you're calling.
Lost refresh token = re-login. Refresh tokens can't be re-issued without a fresh log-in.