Skip to main content

Tokens

Tokens are used to authenticate and authorize access to protected API endpoints. This guide explains how to obtain a token, use it in requests, and follow best practices for token security.

Obtaining a token​

To access protected endpoints, you must first obtain a token from the /token endpoint. See: Retrieve a token

Example request:

curl -X POST https://your-api-domain.com/token \
  -H "Content-Type: application/json" \
  -d '{"username": "your-email@example.com", "password": "your-password"}'

Successful response:

{
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600
}
  • token: The JWT access token for authentication.
  • refresh_token: Use this to obtain a new token when the current one expires.
  • token_type: Always "Bearer".
  • expires_in: Token validity in seconds.

Using the bearer token​

Include the token in the Authorization header for all requests to protected endpoints:

Authorization: Bearer <your-token>

Example:

curl -X GET https://your-api-domain.com/protected-endpoint \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6..."

About JWT tokens​

  • JWT (JSON Web Token) is a compact, URL-safe way to represent claims between two parties.
  • The token contains encoded information (such as user ID, permissions, and expiry) and is cryptographically signed by the server.
  • JWTs are self-contained: the server can validate the token without querying a database for each request.

Token expiry​

  • Tokens are valid for a limited time, specified by the expires_in field.
  • After expiry, use the refresh_token (if provided) to obtain a new access token, or log in again.
  • Using an expired token will result in an authentication error.

Token security best practices​

Take care

Tokens grant access to your account and data. Keep them secure!

  • Keep your token secret: Never share your token or expose it in client-side code, public repositories, or logs.
  • Store tokens securely: Use secure storage mechanisms (such as environment variables or secure HTTP-only cookies).
  • Do not reuse tokens: Always use the latest token provided by the server.
  • Logout if compromised: If you suspect your token is compromised, log out or request a new token immediately.
  • Use HTTPS: Always use HTTPS to prevent token interception.

If you receive an error such as:
You must specify a Bearer token in the Authorization header to access this resource,
ensure you are including the correct header and that your token is valid and unexpired.