Token Management
ChainIT uses JWTs for access and ID tokens, and an opaque refresh token that is not a JWT.
-
Access token: JWT signed with RS256. Verify using your organization’s JWKS URL (the path includes your organization UUID).
-
ID token: JWT signed with RS256 using the same key as the access token. Verify against the same JWKS URL — do not use your client secret.
-
Refresh token: Opaque string (not a JWT); do not parse or verify like a JWT.
OAuth endpoints
Token endpoints depend on the application type:
| Application type | Token endpoint |
|---|---|
| Hosted UI | POST https://develop-auth.chainit.dev/oauth/token |
| M2M | POST https://develop-api.chainit.dev/v1/auth/token |
Hosted UI uses the auth API host from DOCUSAURUS_AUTH_API_BASE_URL at build time. M2M uses the public API host from DOCUSAURUS_PUBLIC_API_BASE_URL. Do not use the Hosted UI token endpoint for M2M applications.
The Hosted UI URL is also shown in the Developer Portal under Application → Advanced → Token Endpoint. The Hosted UI OAuth endpoints — /oauth/authorize, /oauth/token, /oauth/userinfo, /oauth/revoke, /oauth/logout, and /oauth/<orgId>/.well-known/jwks.json — are discoverable at /oauth/.well-known/openid-configuration. See OAuth server metadata.
Token types
| Token Type | Description | Format | Signing / verification |
|---|---|---|---|
| Access Token | Used to access protected APIs | JWT | RS256 + org-scoped JWKS |
| ID Token | OIDC identity claims (requires openid scope) | JWT | RS256 + the same org-scoped JWKS |
| Refresh Token | Used to obtain new tokens without re-login | Opaque | Not a JWT — treat as a secret handle |
| Session Token | Hosted-auth flow session — internal, round-tripped only with ChainIT APIs | JWT | HS256 (internal); consumers never verify this directly |
OAuth applications rotate refresh tokens by default. You can disable this per
app with rotateRefreshTokens: false when a client cannot reliably persist
the new refresh token returned by every refresh call. See
Refresh tokens for the full
refresh-token endpoint reference and rotation behaviour.
Token structure
Access token claims
interface AuthClaims {
aud: string[]; // Audience
azp: string; // Authorized party (clientId)
exp: number; // Expiration timestamp
iat: number; // Issued at timestamp
iss: string; // Issuer
scope: string; // Granted scopes
sub: string; // Subject (userId)
permissions: string[]; // Assigned permissions
}
Signing algorithms
| Algorithm | Usage | Key type |
|---|---|---|
| RS256 | OAuth access tokens and ID tokens | Asymmetric (verify via the org JWKS) |
| HS256 | Internal hosted-auth session tokens (round-tripped to ChainIT only) | Symmetric (internal secret) — not exposed to consumers |
ChainIT signs both access and ID tokens with the same RS256
private key, so a single JWKS lookup verifies both. You never need your
clientSecret to validate ID tokens. The HS256-signed hosted-auth session
token is an internal artifact you pass back to ChainIT — it is not for
third-party verification.
Token expiration options
| Option | Seconds | Description | Use Case |
|---|---|---|---|
ONE_HOUR | 3600 | Short-lived tokens | High-security applications |
TWELVE_HOURS | 43200 | Medium-lived tokens | Standard web applications |
ONE_DAY | 86400 | Daily tokens (default) | Most applications |
SEVEN_DAYS | 604800 | Long-lived tokens | Mobile/offline applications |
Configured per application via tokenExpireTime.
Shorter token lifetimes improve security but require more frequent refresh. Balance security with user experience based on your application's needs.
Token validation
See Token validation for:
Org-scoped JWKS URL for access and ID tokens
RS256 verification (same JWKS for both token types)
Why refresh tokens are not JWTs
- Token introspection endpoint
Client secret rotation
When you rotate clientSecret in the Developer Portal, you can set an optional grace period so previous and new secrets may both work for a limited time while you update deployments. See Grace period.
What to validate
| Claim | Description | How |
|---|---|---|
| Signature | Token was signed by ChainIT | Access and ID: verify RS256 with the org-scoped JWKS. |
exp | Token has not expired | Check exp > now |
iss | Token was issued by expected issuer | Match the iss claim for your environment |
aud | Token is intended for your service | Check audience claim |
scope | Token has required scopes | Check scopes contain needed permission |
orgId | Token belongs to your organization | Validate orgId claim where present |
Next steps
OAuth server metadata — discover endpoints
Token validation — JWKS (RS256), introspection
Token revocation (RFC 7009)
Refresh tokens — refresh-token endpoint and rotation
RP-Initiated Logout (OIDC)
Client secret grace period
- Security best practices