Skip to main content

Token Management

Learn how to manage access tokens effectively.

Token Lifecycle​

1. Request
Obtain a token using OAuth 2.0.
2. Use
Include token in the Authorization header of API requests.
3. Expire
Token expires after 1 hour.
4. Refresh
Request a new token when expired or near expiration.

Caching Tokens​

Cache tokens to avoid unnecessary authentication requests and improve performance.

Implementation strategy

  1. Check cache first • Before requesting a new token, check if you have a valid cached token • Verify it has not expired

  2. Use a time buffer • Consider a token expired 5 minutes before actual expiration • Avoids using a token that expires mid-request

  3. Store token data • Save the access token and expiration timestamp (current time + expires_in) • Use memory, database, or secure file storage

  4. Request new token when needed • If no cached token exists or it is expired or near expiration, request a new one • Update the cache

Handling Token Expiration​

Automatically refresh tokens when they expire to ensure uninterrupted API access.

Automatic refresh strategy

  1. Make API request • Use your cached token in the Authorization header

  2. Check response status • If 2xx, continue • If 401 Unauthorized, the token has expired

  3. Handle 401 • Clear the expired token from cache • Request a new token, then retry the original request

  4. Retry logic • Retry the failed request once with a fresh token • If it fails again, return the error and avoid infinite loops

Proactive refresh (recommended) Check expiration before each request. If the token expires in less than 5 minutes, refresh it first. This reduces request failures and improves reliability.

Security Best Practices​

1. Store credentials securely​

Never hardcode credentials in your code.

Bad practice
  • Hardcoding client ID and secret in source code.
  • Committing credentials to version control.
  • Storing credentials in plain text in the web root.
Good practice

Use environment variables, secure configuration, or secret management.
Example: AWS Secrets Manager, HashiCorp Vault, or CLIENT_SECRET in env.

Note : Keep credentials outside the web root.

2. Use HTTPS only​

Always use HTTPS for all API requests.

  • HTTP is rejected
  • HTTPS encrypts data in transit
  • Verify SSL certificates to prevent man-in-the-middle attacks

3. Protect token storage​

If storing tokens in files or databases:

• File permissions
Restrictive (e.g. 0600 on Unix).
• Location
Outside the web root.
• Encryption
Encrypt sensitive data at rest.
• Access control
Limit which processes or users can read token storage.
• Short-lived apps
Consider in-memory storage only.

4. Implement token rotation​

Rotate client credentials regularly.

  1. Generate new credentials from the Fuuffy dashboard
  2. Update application configuration and test in staging
  3. Deploy to production, then revoke old credentials after confirming the new ones work
  4. Monitor for authentication failures

Rotation schedule Every 90 days for routine rotation. Immediately if credentials are compromised or after team member departures.

Token Validation​

Validate tokens before using them in API requests.

Checklist

  1. Token exists • Present in cache or storage, not null or empty

  2. Expiration data • Stored expiration timestamp is valid

  3. Time remaining • Treat as invalid if it expires in less than 5 minutes

  4. Format • Non-empty string with no unexpected characters or corruption

When validation fails

  • Request a new token
  • Update the cache
  • Retry the operation

Troubleshooting​

Invalid Token Error​

Invalid Token Error

Response schema: application/json
error.code
string
e.g. invalid_token
error.message
string
Human-readable message.
error.details
string
Additional guidance.

Response sample

{
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or expired",
    "details": "Please request a new access token"
  }
}

Common causes

• Token expired (1-hour validity) • Revoked or invalidated • Malformed • From a different environment (e.g. testing vs production)

Solution

  1. Clear the cached token
  2. Request a new access token
  3. Update the cache
  4. Retry the API request

Invalid Client Error​

Invalid Client Error

Response schema: application/json
error.code
string
e.g. invalid_client
error.message
string
Human-readable message.
error.details
string
Additional guidance.

Response sample

{
  "error": {
    "code": "invalid_client",
    "message": "Client authentication failed",
    "details": "Invalid client credentials provided"
  }
}

Common causes

• Wrong client ID or secret • Extra whitespace • Credentials not URL-encoded • Wrong environment • Credentials revoked

Solutions

  1. Verify credentials • Copy from Fuuffy dashboard, no extra spaces

  2. Confirm environment • Use the correct credentials for your environment

  3. URL encoding • Ensure credentials are properly URL-encoded

  4. Contact support • If still failing, contact Fuuffy support • Credentials may need to be regenerated

Next Steps​