Tokens and scopes

Token format#

Every token ScaiKey issues is a signed JWT. Signing algorithm is RS256 by default; the platform can be configured for ES256. Public keys are published at the JWKS endpoint and rotated on a schedule.

Three token shapes:

• Access token — bearer credential for API calls. Carries sub, aud, scope, and a few platform-specific claims.
• ID token — OIDC user-identity assertion. Issued when openid is in the requested scope. Contains identity claims (email, name, groups, etc.) keyed off the requested scopes.
• Refresh token — opaque (not a JWT), one-time-use, hash-stored in the database. Exchanged for a fresh access token at the token endpoint.

Access token claims#

A standard ScaiKey access token looks like this:

1
2
3
4
5
6
7
8
9

{
  "iss": "https://scaikey.scailabs.ai/tenants/{tenant-id}",
  "aud": "<client_id of the audience app>",
  "sub": "<user_id or client_id>",
  "scope": "openid profile email",
  "tenant_id": "tnt_widget0001",
  "exp": 1747584000,
  "iat": 1747580400
}

Additional claims depending on grant and app type:

Note on token_type: the OAuth response envelope also has a field called token_type, which is always "Bearer" (it describes how the token should be used, not what kind of token it is). These are different things at different layers — the response field is RFC 6749 §5.1; the JWT claim is a ScaiKey extension.

Scopes#

Standard OIDC scopes#

ScaiKey admin scopes#

Used by service integrations that call ScaiKey's own admin API. Granted only to applications whose allowed_scopes list includes them.

These are platform-token scopes — they only do anything meaningful on JWTs minted via client_credentials for GLOBAL apps. A user JWT doesn't grant admin access just because the scope is present; the user must also have the appropriate role.

How scopes are constrained#

The token endpoint never grants more than three things permit, simultaneously:

1. What the application's allowed_scopes column lists (registered).
2. What the request asked for (scope=... parameter).
3. For Token Exchange: what the subject token already had (subject_scopes).

If you ask for a scope your app isn't registered for, the token comes back narrower (or, in Token Exchange, with no overlap → invalid_scope error).

Token lifetimes#

A super_admin can change token_lifetime per application via PATCH /api/v1/admin/applications/{id}. The change applies to the next token minted; existing tokens keep their original exp.

For Token Exchange: the exchanged token's lifetime is the target's token_lifetime, not the subject's. A long-running async worker can therefore exchange a near-expiry user token for a fresh full-lifetime audience-restricted token.

Revocation semantics#

ScaiKey access tokens are stateless JWTs. The platform does not maintain a per-token revocation list, and resource servers verify tokens locally against the published JWKS — there's no round-trip to ScaiKey on every API call. The consequence is that admin actions which "revoke" access don't immediately invalidate in-flight access tokens.

The upper-bound staleness window equals the audience application's token_lifetime (default 1 h, configurable down to 5 min for security-sensitive resource servers, or up to 24 h for compute-heavy workloads where re-auth overhead matters).

For workflows that need stronger revocation guarantees:

• Reduce token_lifetime on the resource server's application row (PATCH /api/v1/admin/applications/{id} with token_lifetime). Trade-off: more JWKS verification load on the resource server, more refresh round-trips on the client.
• Implement token introspection on the resource server side via POST /api/v1/oauth/introspect (RFC 7662). Every API call costs one ScaiKey round-trip; in exchange, revocation is instant. Only sensible for low-traffic, high-value endpoints.
• Subscribe to the relevant webhooks (user.suspended, user.deleted, group.member_removed, admin_role.revoked) and invalidate your own session/cache layer in response. Keeps token validation fast and revocation timely.

Verifying tokens#

Standard JWT verification using the public key published at the JWKS endpoint. Steps:

1. Fetch JWKS from $SCAIKEY/api/v1/platform/.well-known/jwks.json (or the tenant equivalent).
2. Read the kid header from the JWT to pick the right key.
3. Verify signature.
4. Validate iss, aud, exp, nbf (if present).
5. Apply scope checks based on your endpoint's policy.

Don't cache the JWKS forever; refresh periodically or on any kid you don't recognize. Keys are rotated occasionally; old keys remain in the JWKS during their grace period so in-flight tokens still validate.