Token Management

Best practices for token management and handling authentication errors

This guide covers best practices for managing access tokens, handling token refresh, and troubleshooting authentication errors.

---

Token Caching

Always cache tokens to avoid unnecessary token requests. Tokens are valid for 1 hour.

Recommended Strategy

1. Cache the token after successful retrieval

2. Track expiration using the expires_in value

3. Refresh proactively before expiration (5-minute buffer recommended)

4. Handle failures by requesting a new token

public class TokenCache
{
    private string _token;
    private DateTime _expiry;
    private readonly SemaphoreSlim _lock = new(1, 1);

    public async Task<string> GetTokenAsync(Func<Task<TokenResponse>> requestToken)
    {
        // Check if token is valid (with 5-minute buffer)
        if (!string.IsNullOrEmpty(_token) && DateTime.UtcNow < _expiry.AddMinutes(-5))
        {
            return _token;
        }

        await _lock.WaitAsync();
        try
        {
            // Double-check after acquiring lock
            if (!string.IsNullOrEmpty(_token) && DateTime.UtcNow < _expiry.AddMinutes(-5))
            {
                return _token;
            }

            var response = await requestToken();
            _token = response.AccessToken;
            _expiry = DateTime.UtcNow.AddSeconds(response.ExpiresIn);

            return _token;
        }
        finally
        {
            _lock.Release();
        }
    }
}

Why Cache Tokens?

Without Caching	With Caching
Token request every API call	One request per hour
Added latency (~100-300ms)	No extra latency
Risk of rate limiting	Minimal auth server load

---

Token Refresh Strategies

Proactive Refresh

Refresh the token before it expires to avoid failed API calls:

class TokenManager {
  private refreshTimer: NodeJS.Timeout | null = null;

  async initialize() {
    await this.refreshToken();
  }

  private async refreshToken() {
    const response = await this.requestToken();
    this.accessToken = response.access_token;

    // Schedule next refresh 5 minutes before expiry
    const refreshIn = (response.expires_in - 300) * 1000;
    this.refreshTimer = setTimeout(() => this.refreshToken(), refreshIn);
  }

  destroy() {
    if (this.refreshTimer) {
      clearTimeout(this.refreshTimer);
    }
  }
}

Reactive Refresh

Refresh when you receive a 401 Unauthorized response:

class ApiClient:
    def __init__(self, token_service):
        self.token_service = token_service
        self._token = None

    def request(self, method, url, **kwargs):
        if not self._token:
            self._token = self.token_service.get_token()

        headers = kwargs.get('headers', {})
        headers['Authorization'] = f'Bearer {self._token}'
        kwargs['headers'] = headers

        response = requests.request(method, url, **kwargs)

        # If unauthorized, refresh token and retry once
        if response.status_code == 401:
            self._token = self.token_service.get_token(force_refresh=True)
            headers['Authorization'] = f'Bearer {self._token}'
            response = requests.request(method, url, **kwargs)

        return response

---

Security Best Practices

1. Secure Credential Storage

Never hardcode credentials in source code or commit them to version control.

Recommended approaches:

Environment	Storage Method
Development	Environment variables, .env files (gitignored)
Production	Secret managers (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
CI/CD	Pipeline secrets, secure variables

// Good: Load from environment
var clientId = Environment.GetEnvironmentVariable("PARTSSOURCE_CLIENT_ID");
var clientSecret = Environment.GetEnvironmentVariable("PARTSSOURCE_CLIENT_SECRET");

// Bad: Hardcoded credentials
var clientId = "186ve3v505rpq71vi24br8c6e3"; // DON'T DO THIS

2. Use HTTPS Only

All API communication must use HTTPS. HTTP requests will be rejected or redirected.

3. Validate Token Responses

Always check for errors in token responses:

const response = await fetch(tokenEndpoint, options);

if (!response.ok) {
  const error = await response.json();
  throw new AuthenticationError(
    `Token request failed: ${error.error} - ${error.error_description}`
  );
}

4. Implement Token Isolation

If your application serves multiple clients, isolate tokens:

public class MultiTenantTokenService
{
    private readonly ConcurrentDictionary<string, TokenCache> _tokensByClient = new();

    public async Task<string> GetTokenAsync(string clientId, string clientSecret)
    {
        var cache = _tokensByClient.GetOrAdd(clientId, _ => new TokenCache());
        return await cache.GetTokenAsync(() => RequestToken(clientId, clientSecret));
    }
}

5. Log Authentication Events

Log authentication events for debugging (but never log secrets):

_logger.LogInformation(
    "Token obtained. ClientId: {ClientId}, ExpiresIn: {ExpiresIn}",
    clientId,
    response.ExpiresIn);

// Never log this:
// _logger.LogInformation("Secret: {Secret}", clientSecret); // DON'T DO THIS

---

Error Handling

Token Request Errors

Error	Cause	Solution
invalid_client	Wrong client_id or client_secret	Verify credentials
invalid_request	Missing required parameters	Check request format
invalid_scope	Scope doesn't exist or not authorized	Verify scope name
unsupported_grant_type	Wrong grant_type value	Use client_credentials

API Authentication Errors

Status	Meaning	Action
401 Unauthorized	Token invalid or expired	Refresh token and retry
403 Forbidden	Token valid but lacks permission	Check scope/permissions

Retry Logic

Implement exponential backoff for transient errors:

public async Task<string> GetTokenWithRetry(int maxRetries = 3)
{
    for (int attempt = 0; attempt < maxRetries; attempt++)
    {
        try
        {
            return await RequestToken();
        }
        catch (HttpRequestException ex) when (attempt < maxRetries - 1)
        {
            var delay = TimeSpan.FromSeconds(Math.Pow(2, attempt));
            _logger.LogWarning(ex,
                "Token request failed, retrying in {Delay}s",
                delay.TotalSeconds);
            await Task.Delay(delay);
        }
    }

    throw new AuthenticationException("Failed to obtain token after retries");
}

---

Troubleshooting

"invalid_client" Error

1. Verify client_id - Check for typos or extra whitespace

2. Verify client_secret - Ensure you're using the correct secret

3. Check environment - Make sure you're using the right credentials for the environment (prod vs QA)

"invalid_scope" Error

1. Check scope format - Should be default-m2m-resource-server-p2hkah/admin:internal

2. Verify authorization - Confirm your client is authorized for the requested scope

3. Contact support - If the scope should be valid, contact [email protected]

Token Works in Postman but Not in Code

1. Check Content-Type - Must be application/x-www-form-urlencoded

2. Verify encoding - Special characters in credentials must be URL-encoded

3. Check for whitespace - Trim any leading/trailing whitespace from credentials

401 Errors After Token Refresh

1. Check clock sync - Ensure your server's clock is synchronized (NTP)

2. Verify token - Decode the JWT at jwt.io to check claims

3. Check expiration - The exp claim should be in the future

Intermittent Authentication Failures

1. Implement retry logic - Network issues can cause transient failures

2. Check for race conditions - Ensure token refresh is thread-safe

3. Monitor token expiry - Refresh tokens proactively, not reactively

---

Complete Example

A production-ready token management implementation:

public interface ITokenService
{
    Task<string> GetAccessTokenAsync();
}

public class TokenService : ITokenService, IDisposable
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<TokenService> _logger;
    private readonly string _tokenEndpoint;
    private readonly string _clientId;
    private readonly string _clientSecret;
    private readonly string _scope;

    private string _accessToken;
    private DateTime _tokenExpiry;
    private readonly SemaphoreSlim _refreshLock = new(1, 1);

    public TokenService(
        IHttpClientFactory httpClientFactory,
        ILogger<TokenService> logger,
        IConfiguration configuration)
    {
        _httpClient = httpClientFactory.CreateClient();
        _logger = logger;
        _tokenEndpoint = configuration["PartsSource:TokenEndpoint"];
        _clientId = configuration["PartsSource:ClientId"];
        _clientSecret = configuration["PartsSource:ClientSecret"];
        _scope = configuration["PartsSource:Scope"];
    }

    public async Task<string> GetAccessTokenAsync()
    {
        // Return cached token if valid
        if (IsTokenValid())
        {
            return _accessToken;
        }

        await _refreshLock.WaitAsync();
        try
        {
            // Double-check after acquiring lock
            if (IsTokenValid())
            {
                return _accessToken;
            }

            await RefreshTokenAsync();
            return _accessToken;
        }
        finally
        {
            _refreshLock.Release();
        }
    }

    private bool IsTokenValid()
    {
        return !string.IsNullOrEmpty(_accessToken)
            && DateTime.UtcNow < _tokenExpiry.AddMinutes(-5);
    }

    private async Task RefreshTokenAsync()
    {
        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("grant_type", "client_credentials"),
            new KeyValuePair<string, string>("client_id", _clientId),
            new KeyValuePair<string, string>("client_secret", _clientSecret),
            new KeyValuePair<string, string>("scope", _scope)
        });

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

        if (!response.IsSuccessStatusCode)
        {
            var error = await response.Content.ReadAsStringAsync();
            _logger.LogError("Token request failed: {Error}", error);
            throw new AuthenticationException($"Failed to obtain token: {error}");
        }

        var tokenResponse = await response.Content
            .ReadFromJsonAsync<TokenResponse>();

        _accessToken = tokenResponse.AccessToken;
        _tokenExpiry = DateTime.UtcNow.AddSeconds(tokenResponse.ExpiresIn);

        _logger.LogInformation(
            "Token refreshed. Expires at {Expiry}",
            _tokenExpiry);
    }

    public void Dispose()
    {
        _refreshLock?.Dispose();
    }
}