Authentication Flow
Login, token management, and session lifecycle
Authentication
This guide covers the complete authentication flow for accessing the PRIME API.
Overview
The platform supports two authentication methods:
- JWT Bearer Tokens - For user sessions (web/mobile clients)
- API Keys - For programmatic access (see API Key Creation)
Prerequisites
- Valid user credentials (username/password)
- TOTP authenticator configured (if 2FA is enabled)
Step 1: Login
Authenticate with username and password.
Endpoint: POST /api/rest/v1/users/authentication/login
Request
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/login \
-H "Content-Type: application/json" \
-d '{
"username": "[email protected]",
"password": "your-password"
}'Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
username | string | Yes | Username of the user |
password | string | Yes | Password of the user |
challenge | string | No | TOTP code if 2FA is enabled for the user |
recaptchaToken | string | No | reCAPTCHA token if required |
deviceId | string | No | Optional device identifier to override a previous session |
Response (200 OK)
{
"result": {
"accessToken": "eyJhbGciOiJSUzI1NiIs...",
"refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29",
"accessExpiresAt": "2024-01-15T11:30:00Z",
"sessionExpiresAt": "2024-01-22T10:30:00Z"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
result.accessToken | string | JWT access token for API requests |
result.refreshToken | string (UUID) | Token to refresh the session |
result.accessExpiresAt | timestamp | When the access token expires |
result.sessionExpiresAt | timestamp | When the session expires |
Step 2: Login with 2FA
If 2FA is enabled, include the TOTP code in the challenge field.
Request
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/login \
-H "Content-Type: application/json" \
-d '{
"username": "[email protected]",
"password": "your-password",
"challenge": "123456"
}'The response is the same as a successful login without 2FA.
Step 3: Using the Access Token
Include the access token in the Authorization header for all subsequent API requests.
curl -X GET https://api.t-dx.com/api/rest/v1/users/me \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."Step 4: Refreshing Tokens
Before the access token expires, use the refresh token to obtain a new one.
Endpoint: POST /api/rest/v1/users/authentication/refresh
Request
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/refresh \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29"
}'Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
refreshToken | string (UUID) | Yes | Session token to refresh |
Response (200 OK)
{
"result": {
"accessToken": "eyJhbGciOiJSUzI1NiIs...",
"refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29",
"accessExpiresAt": "2024-01-15T12:30:00Z",
"sessionExpiresAt": "2024-01-22T10:30:00Z"
}
}Step 5: Logout
Invalidate the current session or all sessions.
Endpoint: POST /api/rest/v1/users/authentication/logout
Request (Logout specific session)
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/logout \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "5321bef2-155d-40c7-aa63-5d18f5f6dc29"
}'Request (Logout all sessions)
curl -X POST https://api.t-dx.com/api/rest/v1/users/authentication/logout \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{}'Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
refreshToken | string (UUID) | No | Specific session to invalidate. If omitted, all sessions are invalidated. |
Response (200 OK)
Empty response on success.
Error Scenarios
| Status | Code | Description |
|---|---|---|
| 401 | UNAUTHENTICATED | Invalid credentials or missing 2FA code |
| 403 | ACCOUNT_IS_SUSPENDED | Account suspended |
| 429 | RESOURCE_EXHAUSTED | Too many login attempts |
Related
- API Key Creation - Create API keys for programmatic access
- Getting Started: Authentication - Detailed auth documentation
Updated 5 days ago