Caching (Token Caching)
What is token caching?
Token caching is the practice of storing an API token after you mint it so your application can reuse it for later requests.
Bandwidth OAuth 2.0 access tokens expire after one hour. Cache each token until it expires instead of requesting a new token before every API call.
How token caching works
- Send a POST request to the Bandwidth token endpoint with your Client ID, your Client Secret, and
grant_type=client_credentials. - Read the
access_tokenandexpires_invalues in the response. Anexpires_invalue of 3600 means the token stays valid for one hour. - Store the token and its expiration time in memory or in a shared cache, such as Redis.
- Send the token as a
Bearertoken in the Authorization header of each API request. - Request a new token 5 to 10 seconds before the cached token expires, then replace the cached copy.
Mint and store tokens on a server in a secure environment. Never place your Client Secret or a token in client-side code.
How Bandwidth is involved with token caching
Bandwidth issues OAuth 2.0 access tokens as JSON Web Tokens (JWTs) through the client credentials flow, the only grant type the token endpoint supports. Bandwidth recommends that you reuse a token for its full lifetime.
Several workers or services can share one token without conflict. Bandwidth also allows more than one valid token to exist for the same Client ID at the same time, with no limit on concurrent tokens.
If you use a current Bandwidth SDK, you can skip the cache code. Provide your Client ID and Client Secret, and the SDK retrieves and refreshes tokens for you.
Bandwidth is retiring legacy API User (Basic Authentication) credentials on December 2, 2026. After that date, OAuth 2.0 client credentials are the supported method.
What are the benefits of token caching?
- Your application sends one token request per hour instead of one per API call, which removes a network round trip from every request.
- Workers and services that share a cache reuse the same token, so you avoid duplicate token requests across your fleet.
- Your Client Secret travels over the network once an hour instead of with every request.
Token caching FAQs
Minting a token means requesting a new access token from the Bandwidth token endpoint. Caching means storing that token so you can reuse it until it expires.
Cache the token for the lifetime in the expires_in field, currently 3600 seconds (one hour). Refresh it 5 to 10 seconds early to help avoid sending a request with an expired token.
Request a new token from the token endpoint with your current Client ID and Client Secret, then replace the cached token.
Yes. Multiple workers or services can use the same token at the same time without conflict.
No. Bandwidth SDKs that support OAuth 2.0 handle token retrieval and refreshing when you initialize them with your Client ID and Client Secret.
Related:
- Bandwidth Credential Management guide: https://dev.bandwidth.com/docs/account/credentials/management
- Bandwidth auth service OpenAPI spec, “Mint Token”:
https://dev.bandwidth.com/spec/auth-service-oauth.yml - Bandwidth Help Center, FAQ “Can I reuse an OAuth access token?”: https://www.bandwidth.com/support/en/articles/13004306-creating-and-managing-your-bandwidth-api-credentials
