Token Management
Learn about access tokens, refresh tokens, ID tokens, and how to manage them securely.
Access Tokens
Type:JWT (JSON Web Token) signed with HS256
Expiration:30 minutes (1800 seconds) from issuance
Usage:Include the token in the Authorization header as a Bearer token
JWT Claims
| Claim | Type | Status | Description |
|---|---|---|---|
| sub | string | Required | User ID (subject identifier) |
| string | Required | User's email address | |
| client_id | string | Required | Your application's client ID |
| scope | string | Required | Space-separated list of granted scopes |
| exp | number | Required | Expiration timestamp (Unix time) |
| iat | number | Required | Issued at timestamp (Unix time) |
Refresh Tokens
Type:JWT (JSON Web Token) signed with HS256
Expiration:7 days from issuance
Usage:Exchange this token for new access and refresh tokens via the token endpoint
JWT Claims
| Claim | Type | Status | Description |
|---|---|---|---|
| sub | string | Required | User ID (subject identifier) |
| exp | number | Required | Expiration timestamp (Unix time) |
| iat | number | Required | Issued at timestamp (Unix time) |
ID Tokens
Type:JWT (JSON Web Token) signed with HS256
Purpose:Contains user identity information per OpenID Connect specification
JWT Claims (Standard OpenID Connect)
| Claim | Type | Status | Description |
|---|---|---|---|
| sub | string | Required | User ID (subject identifier) |
| name | string | Required | User's display name |
| preferred_username | string | Required | User's username |
| string | Required | User's email address | |
| email_verified | boolean | Required | Email verification status |
| picture | string | Required | URL to user's avatar image |
| avatarUrl | string | Required | Alternative avatar URL field |
| client_id | string | Required | Your application's client ID |
| nonce | string | Optional | Nonce value (only if provided in authorization request) |
| exp | number | Required | Expiration timestamp (Unix time) |
| iat | number | Required | Issued at timestamp (Unix time) |
Token Refresh Flow
When an access token expires (after 30 minutes), use the refresh token to obtain new tokens without requiring user interaction. Refresh tokens proactively before the access token expires:
POST /api/v2/oauth/token
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "YOUR_REFRESH_TOKEN",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET"
}Successful response (200 OK):
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Token Revocation & Blacklisting
Users can revoke access to your application at any time through their account settings. When a user revokes access:
- Cengel ID removes the consent grant from the system
- We blacklist all existing tokens (access, refresh, ID)
- The API returns
403 Forbiddenfor requests with revoked tokens - Token refresh attempts also fail with
403 Forbidden
Handle 401/403 responses gracefully:
- Detect token revocation by checking for 403 responses with "Access revoked by user" error
- Clear stored tokens from your system
- Prompt the user to re-authenticate by redirecting to the authorization endpoint
- Don't automatically retry with the same token
Account Status & Token Validity
Cengel ID invalidates tokens when the user's account status changes:
- Banned accounts:We immediately invalidate all tokens. The API returns
403 Forbiddenwith "Account banned" error. - Suspended accounts:We invalidate tokens. The API returns
403 Forbiddenwith "Account is suspended" error. - Expired bans:If a ban expires, we automatically reactivate the account, but existing tokens remain invalid. The user must re-authenticate.
Handle these error responses gracefully and provide clear feedback to users about why authentication failed.