JWT Authentication for Token of Trust API

Token of Trust now supports JWT (JSON Web Token) authentication as an alternative to using API keys directly on every request.

How It Works

1. Exchange your API credentials for a JWT token
2. Use the token in the Authorization header for subsequent API requests
3. Request a new token when it expires

Step 1: Obtain a JWT Token

Exchange your Token of Trust API credentials for a JWT token.

Endpoint

POST https://api.tokenoftrust.com/api/internal/auth/token

Request Body

{
  "appDomain": "myapp.com",
  "totApiKey": "your-public-api-key",
  "totSecretKey": "your-secret-key"
}

Parameters

appDomain - Your application's domain

totApiKey - Your public API key

totSecretKey - Your secret key

Success Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "expiresAt": "2025-10-29T18:38:22.000Z"
}

The token value is what you'll use for authentication. It expires in 15 minutes.

Error Responses

401 Unauthorized - Invalid credentials

403 Forbidden - API key lacks necessary permissions

Step 2: Use the Token

Include the JWT token in the Authorization header for API requests:

Header Format

Authorization: Bearer <your-token>

Example

curl -X GET https://qa.tokenoftrust.com/api/your/endpoint \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Step 3: Verify Your Token

You can check your token's validity and expiration at any time.

Endpoint

GET https://qa.tokenoftrust.com/api/internal/auth/token

Request

curl -X GET https://qa.tokenoftrust.com/api/internal/auth/token \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Success Response

{
  "valid": true,
  "appDomain": "myapp.com",
  "issuedAt": "2025-10-29T18:23:22.000Z",
  "expiresAt": "2025-10-29T18:38:22.000Z"
}

Error Response

401 Unauthorized - Token is invalid, expired, or malformed

Complete Example

Here's a complete workflow:

1. Get a Token

curl -X POST https://qa.tokenoftrust.com/api/internal/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "appDomain": "myapp.com",
    "totApiKey": "pk_live_abc123...",
    "totSecretKey": "sk_live_xyz789..."
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 900,
  "expiresAt": "2025-10-29T18:38:22.000Z"
}

2. Use the Token

curl -X GET https://qa.tokenoftrust.com/api/your/endpoint \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

3. When Token Expires

Tokens expire after 15 minutes. When you receive a 401 error with "Token has expired", simply request a new token.

Important Notes

Token Expiration

Tokens are valid for 15 minutes from issuance. You cannot refresh tokens - you must request a new one when it expires.

Permissions

Your token will include the same permissions as your API key. All tokens automatically include the ability to manage API keys.

Common Questions

Can I refresh a token before it expires?

No, tokens cannot be refreshed. Request a new token when needed.

What happens if my token expires mid-request?

You'll receive a 401 Unauthorized response. Simply request a new token and retry.