AnyRoad provides two primary methods for authenticating API requests:
Temporary API Keys - Short-lived credentials for quickly evaluating, and testing API requests with no refresh capabilities
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:
Go to the Settings tab in your Dashboard
Click on API & Token Management
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.
From the generate API Credential screen, you have the option to create an expiry date for this client credential and client secret for added security.
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 (theidfrom the API key creation response)client_secret(required): The full API key value (thekeyfrom 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 requeststoken_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/tokenendpoint
Example API Request
curl -H "Authorization: Bearer youraccesstokenxyz" \
<https://app.anyroad.com/api/v1/experiences>
Important:
Do not include quotes around the token value
Ensure there is a single space between "Bearer" and the token
The token must be valid and not expired (tokens expire after 1 hour)
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
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"
}'
The OAuth 2.0 Client Credential flow is mature, and nearly every platform has supporting libraries or code examples for easily implementing this flow in your application.
Important: Since access tokens expire after 1 hour, you should implement logic in your application to request a new token before the current one expires. Store your client_id and client_secret securely and use them to generate new tokens as needed.
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
Error Code | Description | Action |
| Client credentials are invalid | Verify client_id and client_secret |
| Grant type not supported | Use |
| Authorization grant is invalid | Check token format and validity |
| Token is expired or invalid | Refresh or request new token |
| Request is malformed | Check request format and parameters |
Best Practices
Security
Store Credentials Securely
Never hardcode API keys or client secrets in your source code
Use environment variables or secure credential stores
Rotate credentials regularly
Use HTTPS
Always use HTTPS for API requests
Never send credentials over unencrypted connections
Token Management
Implement automatic token refresh before expiration
Handle token expiration gracefully in your application
Revoke unused or compromised tokens immediately
Performance
Token Caching
Cache access tokens until they expire
Implement proper cache invalidation
Avoid requesting new tokens for every API call
Rate Limiting
Respect API rate limits
Implement exponential backoff for retries
Monitor your API usage
Development
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 [email protected].