Reusing client_credential bearer tokens for the token's full lifetime.

OAuth 2.0 Bearer Token Caching Best Practices

This guide covers best practices for caching and reusing OAuth 2.0 bearer tokens when integrating with Snapdocs APIs. Implementing token caching reduces latency, minimizes load on the authorization server, and improves the overall reliability of your integration.

Overview

Snapdocs APIs use OAuth 2.0 with the client_credentials grant type. When you request a token, the response includes an expires_in field indicating how long the token remains valid (typically 2 hours / 7200 seconds). By caching the token and reusing it for its full lifetime, your application avoids the overhead of fetching a new token on every API call.

Benefits of Token Caching

How Token Caching Works

The following diagram illustrates the recommended flow. Your application checks for a cached token before each API call and only requests a new one when the cache is empty or the token has expired.

sequenceDiagram
    participant Client as Your Application
    participant Cache as Token Cache (Redis/Memory)
    participant Auth as Auth0 (Token Endpoint)
    participant API as Snapdocs API

    Client->>Cache: Check for cached token
    Cache-->>Client: Cache MISS
    Client->>Auth: POST /oauth/token (client_credentials)
    Auth-->>Client: { access_token, expires_in: 7200 }
    Client->>Cache: Store token (TTL = expires_in - 60s buffer)
    Client->>API: API request with Bearer token
    API-->>Client: 200 OK

    Note over Client,Cache: Subsequent API call (within token lifetime)
    Client->>Cache: Check for cached token
    Cache-->>Client: Cache HIT ✅
    Client->>API: API request with Bearer token
    API-->>Client: 200 OK

    Note over Client,Auth: Token fetched only when cache is empty or expired

Token Lifecycle Decision Flow

Use this decision diagram to determine when your application should fetch a new token vs. reuse the cached one.

flowchart TD
    A[API Call Needed] --> B{Cached token exists?}
    B -- No --> C[Fetch new token from Auth0]
    C --> D[Cache token with TTL = expires_in - 60s]
    D --> E[Make API call with Bearer token]
    B -- Yes --> F{Token expired or near expiry?}
    F -- No --> E
    F -- Yes --> C
    E --> G{Response 401 Unauthorized?}
    G -- No --> H[Process response]
    G -- Yes --> I[Invalidate cached token]
    I --> C

Implementation Guide

Step 1: Store the Token with Expiration Metadata

When you receive a token response from Auth0, store both the access_token and its calculated expiration time.

A typical Auth0 token response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200
}

Step 2: Check Cache Before Every API Call

Before making any API call, check your cache for a valid token. Only fetch a new one if the cache is empty or the token has expired.

Step 3: Handle 401 Responses Gracefully

If the API returns a 401 Unauthorized, the token may have been revoked or is otherwise invalid. Invalidate your cached token, fetch a new one, and retry the request once.

Code Examples

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading;
using System.Threading.Tasks;

public class SnapdocsTokenManager
{
    private const int BufferSeconds = 60;

    private readonly string _clientId;
    private readonly string _clientSecret;
    private readonly string _audience;
    private readonly string _tokenUrl;
    private string _accessToken;
    private DateTime _expiresAt = DateTime.MinValue;
    private readonly SemaphoreSlim _semaphore = new(1, 1);
    private static readonly HttpClient _httpClient = new();

    public SnapdocsTokenManager(string clientId, string clientSecret,
                                 string audience, string tokenUrl)
    {
        _clientId = clientId;
        _clientSecret = clientSecret;
        _audience = audience;
        _tokenUrl = tokenUrl;
    }

    public async Task<string> GetTokenAsync()
    {
        if (IsTokenValid()) return _accessToken;

        await _semaphore.WaitAsync();
        try
        {
            if (IsTokenValid()) return _accessToken;
            await FetchNewTokenAsync();
            return _accessToken;
        }
        finally
        {
            _semaphore.Release();
        }
    }

    public void Invalidate()
    {
        _accessToken = null;
        _expiresAt = DateTime.MinValue;
    }

    private bool IsTokenValid() =>
        _accessToken != null && DateTime.UtcNow < _expiresAt;

    private async Task FetchNewTokenAsync()
    {
        var payload = new
        {
            client_id = _clientId,
            client_secret = _clientSecret,
            audience = _audience,
            grant_type = "client_credentials"
        };

        var content = new StringContent(
            JsonSerializer.Serialize(payload),
            Encoding.UTF8, "application/json");

        var response = await _httpClient.PostAsync(_tokenUrl, content);
        response.EnsureSuccessStatusCode();

        var json = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
        _accessToken = json.RootElement.GetProperty("access_token").GetString();
        var expiresIn = json.RootElement.TryGetProperty("expires_in", out var exp)
            ? exp.GetInt32() : 7200;
        _expiresAt = DateTime.UtcNow.AddSeconds(expiresIn - BufferSeconds);
    }
}

Choosing a Cache Backend

Any of the following approaches will work. Choose the one that best fits your existing infrastructure:

Multi-Service / Distributed Architecture

If your integration spans multiple services that each call Snapdocs APIs, consider a centralized token service:

flowchart LR
    subgraph Your Infrastructure
        SA[Service A] --> TS[Token Service / Cache]
        SB[Service B] --> TS
        SC[Service C] --> TS
        TS --- Redis[(Redis / Shared Cache)]
    end

    TS -->|Fetch on cache miss| Auth[Auth0 Token Endpoint]
    SA -->|Bearer Token| API[Snapdocs API]
    SB -->|Bearer Token| API
    SC -->|Bearer Token| API

Estimated Implementation Timeline

Summary

1. Fetch a token once from Auth0 using the client_credentials grant
2. Cache the token with a TTL of expires_in - 60 seconds (buffer for clock skew)
3. Reuse the cached token for all API calls within the TTL window
4. On 401 response, invalidate the cache and fetch a new token
5. Thread safety — use a mutex/lock to prevent concurrent token fetches