# 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 \ -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 ``` - **"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" \ ``` ### **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": "", "title": "Invalid Client", "status": 401, "error": "invalid_client", "error_description": "Client authentication failed" } ``` #### **Unsupported Grant Type (400)** ``` { "type": "", "title": "Invalid Grant", "status": 400, "error": "unsupported_grant_type", "error_description": "The authorization grant type is not supported" } ``` #### **Expired Token (401)** ``` { "type": "", "title": "Unauthorized", "status": 401, "error": "invalid_token", "error_description": "The access token provided is expired" } ``` #### **Error Codes Reference** | Error Code | Description | Action | |-------------------------|-----------------------------------------|---------------------------------------------------| | `invalid_client` | Client credentials are invalid | Verify client_id and client_secret | | `unsupported_grant_type`| Grant type not supported | Use `client_credentials` or `refresh_token` | | `invalid_grant` | Authorization grant is invalid | Check token format and validity | | `invalid_token` | Token is expired or invalid | Refresh or request new token | | `invalid_request` | Request is malformed | Check request format and parameters | ## **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](https://developer.anyroad.com/) - **Status Page**: [status.anyroad.com](https://status.anyroad.com/) If you have any additional questions, you can contact our Customer Experience team via chat or at [support@anyroad.com](mailto:support@anyroad.com).