API & Token Management

October 21, 2025

AnyRoad provides two primary methods for authenticating API requests:

1. Temporary API Keys - Short-lived credentials for quickly evaluating, and testing API requests with no refresh capabilities.
2. OAuth 2.0 Client Credentials Flow - Short-lived access tokens with automatic refresh capabilities.

In this article you will learn about authentication methods, their use cases, and implementation details.

Temporary API Keys

To generate a temporary API key:

1. Go to the Settings tab in your Dashboard
2. Click on API & Token Management
3. And then Generate Access Token

This will generate a short-lived access token (60 minutes) to evaluate and develop integrations with AnyRoad API's. For a production integration you will need to implement an OAuth 2.0 Client Credentials Flow.

OAuth 2.0 Client Credentials Flow

The OAuth 2.0 Client Credentials flow is designed for server-to-server authentication where your application needs to access API resources on behalf of itself (not on behalf of a user). This flow provides short-lived access tokens that can be refreshed automatically.

Generate API Credential

From the API & Token Management screen, you can generate a new client ID and client secret. To manage client ID's and client secrets, navigate to the Settings tab on your Dashboard and then click on API & Token Management. These credentials will be used to both generate and refresh API tokens.

Note: if you choose to have an expiry date for a credential, you must generate new credentials and update your implementation before those credentials expire, or your integration may stop working.

Make sure to copy and store your client secret before closing out the modal window, as your client secret will never be accessible after the modal is closed.

Deactivate credential

Click the three-dot menu for any credential to deactivate it. This will not expire or revoke an existing token generated from a credential, but it will prevent a refresh of an existing token from happening.

Authentication Endpoint

Use your generated client credentials to request API tokens from the authentication endpoint that can be used to make API calls.

Token Endpoint

POST /accounts/oauth/token

Request Headers

Content-Type: application/json

Parameters:

• grant_type (required): Must be "client_credentials"
• client_id (required): Your API credential ID (the id from the API key creation response)
• client_secret (required): The full API key value (the key from the API key creation response)

Response

{
  "access_token": "yourclientaccesstokenxyz",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Response Fields:

• access_token: The JWT access token for API requests
• token_type: Always "Bearer"
• expires_in: Token lifetime in seconds (default: 3600 seconds = 1 hour)
• scope: Space-separated list of granted scopes

Example CURL Request

curl -X POST <https://app.anyroad.com/accounts/oauth/token> \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

Example Response:

{
  "access_token": "youraccesstokenxyz",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Using Access Tokens

Once you have an access token, you must include it in the Authorization header of every API request. The header value must follow the Bearer authentication scheme, which requires the word "Bearer" followed by a space and then your access token.

Authorization Header Format

Authorization: Bearer <your_access_token>

• "Bearer": This keyword identifies the authentication scheme. It must be included exactly as shown (capital "B", followed by a space)
• Access Token: The JWT token received from the /accounts/oauth/token endpoint

Example API Request

curl -H "Authorization: Bearer youraccesstokenxyz" \
     <https://app.anyroad.com/api/v1/experiences>

Token Refresh

When your access token is about to expire, you need to generate a new token using your client credentials. As AnyRoad does not currently support refresh tokens, you must re-authenticate with your client credentials to get a new access token.

Generate New Access Token

Token Management

Token Introspection

You can verify token validity and get token information:

Introspection Endpoint

POST /accounts/oauth/introspect

Request Body

{
  "token": "youraccesstokenxyz"
}

Response

{
  "active": true,
  "scope": "read write",
  "client_id": "your_client_id",
  "token_type": "Bearer",
  "exp": 1642248000,
  "iat": 1642244400,
  "sub": "us_1234567890",
  "aud": "anyroad",
  "iss": "anyroad",
  "jti": "unique_token_id"
}

Token Revocation

To revoke a token:

Revocation Endpoint

POST /accounts/oauth/revoke

Request Body

{
  "token": "youraccesstokenxyz",
  "token_type_hint": "access_token"
}

Error Handling

Common Error Responses

Invalid Client Credentials (401)

{
  "type": "<https://example.com/error-type>",
  "title": "Invalid Client",
  "status": 401,
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Unsupported Grant Type (400)

{
  "type": "<https://example.com/error-type>",
  "title": "Invalid Grant",
  "status": 400,
  "error": "unsupported_grant_type",
  "error_description": "The authorization grant type is not supported"
}

Expired Token (401)

{
  "type": "<https://example.com/error-type>",
  "title": "Unauthorized",
  "status": 401,
  "error": "invalid_token",
  "error_description": "The access token provided is expired"
}

Error Codes Reference

Best Practices

Security

1. Store Credentials Securely

   • Never hardcode API keys or client secrets in your source code.
   • Use environment variables or secure credential stores.
   • Rotate credentials regularly.

2. Use HTTPS

   • Always use HTTPS for API requests.
   • Never send credentials over unencrypted connections.

3. Token Management

   • Implement automatic token refresh before expiration.
   • Handle token expiration gracefully in your application.
   • Revoke unused or compromised tokens immediately.

Performance

1. Token Caching

   • Cache access tokens until they expire.
   • Implement proper cache invalidation.
   • Avoid requesting new tokens for every API call.

2. Rate Limiting

   • Respect API rate limits.
   • Implement exponential backoff for retries.
   • Monitor your API usage.

Development

1. Error Handling
   • Implement comprehensive error handling.
   • Log authentication failures for debugging.
   • Provide meaningful error messages to users.

Support

For additional support or questions about API authentication:

• Documentation: AnyRoad Developer Portal
• Status Page: status.anyroad.com

If you have any additional questions, you can contact our Customer Experience team via chat or at support@anyroad.com.