Skip to main content

​
Overview

The Authentication API provides endpoints for issuing and refreshing JWT tokens. These endpoints are used to authenticate users and maintain their sessions.

​
Generate Token

Issue JWT access and refresh tokens by submitting user credentials. 
curl -X POST https://api.example.com/api/v1/identity/token/issue \
  -H "Content-Type: application/json" \
  -H "tenant: root" \
  -d '{
    "email": "[email protected]",
    "password": "YourPassword123!"
  }'

​
HTTP Request

POST /api/v1/identity/token/issue

​
Headers

​
tenant
string
default:"root"
The tenant context for authentication. Defaults to ‘root’ if not provided.

​
Request Body

​
email
string
required
User’s email address
​
password
string
required
User’s password

​
Response

​
accessToken
string
JWT access token for API authentication
​
refreshToken
string
Refresh token used to obtain new access tokens
​
refreshTokenExpiresAt
datetime
Expiration timestamp for the refresh token
​
accessTokenExpiresAt
datetime
Expiration timestamp for the access token

​
Response Example

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "7a4f3e9c2b1d8e6f5a3c2b1d9e8f7a6c",
  "refreshTokenExpiresAt": "2026-04-06T10:30:00Z",
  "accessTokenExpiresAt": "2026-03-07T10:30:00Z"
}

​
Error Responses

​
401
error
Unauthorized - Invalid email or password
​
400
error
Bad Request - Invalid request format or missing required fields
​
500
error
Internal Server Error - An unexpected error occurred

​
Refresh Token

Use a valid (possibly expired) access token together with a valid refresh token to obtain new tokens. 
curl -X POST https://api.example.com/api/v1/identity/token/refresh \
  -H "Content-Type: application/json" \
  -H "tenant: root" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "7a4f3e9c2b1d8e6f5a3c2b1d9e8f7a6c"
  }'

​
HTTP Request

POST /api/v1/identity/token/refresh

​
Headers

​
tenant
string
required
The tenant context for token refresh

​
Request Body

​
token
string
required
The current access token (may be expired)
​
refreshToken
string
required
The valid refresh token

​
Response

​
token
string
New JWT access token
​
refreshToken
string
New rotated refresh token (the old refresh token is invalidated)
​
refreshTokenExpiryTime
datetime
Expiration timestamp for the new refresh token

​
Response Example

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.new_token...",
  "refreshToken": "9b5e4d8f3c2a1e7d6b4a3c2e1f8d7b6a",
  "refreshTokenExpiryTime": "2026-04-06T10:35:00Z"
}

​
Error Responses

​
401
error
Unauthorized - Invalid or expired refresh token
​
400
error
Bad Request - Invalid request format or missing required fields
​
500
error
Internal Server Error - An unexpected error occurred

​
Notes

  • Refresh tokens are rotated on each use for security purposes
  • The old refresh token becomes invalid immediately after a successful refresh
  • Both access and refresh tokens are scoped to the tenant specified in the header

Build docs developers (and LLMs) love

Get started for freeTalk to us