Skip to main content

Authentication

This guide covers authentication methods for the OpenAge API, including API key management, security best practices, and troubleshooting authentication issues.

Authentication overview​

OpenAge uses API key-based authentication for all API requests. Each API key is associated with a specific product and has configurable permissions and rate limits.

API key authentication​

Authentication method​

All API requests must include a valid API key in the Authorization header by using the Bearer token format:

Authorization: Bearer your-api-key

Example request​

curl -X GET "https://prod.ageapi.org/api/v1/age-verification/get-status?id=verification-id" \
  -H "Authorization: Bearer your-api-key" \
  -H "Accept: application/json"

Product test and live modes​

  • Test Mode: Use test.prod.ageapi.org hostname with test API keys
  • Live Mode: Use prod.ageapi.org hostname with live API keys

Each mode has completely separate API keys and configurations. In test mode you can use provider test credentials (for example, test cards and test IDs) to simulate outcomes; it can't produce real, verified results for real users. See Testing and development considerations for details.

Security best practices​

API key protection​

  • Server-Side Only: Never expose API keys in client-side code
  • Key Rotation: Regularly rotate API keys for enhanced security
  • Access Control: Implement proper access controls for API key management

Request security​

  • Header Validation: Ensure proper headers are included in requests
  • Error Handling: Handle authentication errors gracefully

API key management​

Key features​

  • Multiple Keys: You can have multiple valid API keys at the same time
  • Expiration Dates: API key expiration dates can be updated at any time
  • Easy Rotation: Create new keys before deleting old ones for seamless rotation
  • Test/Live Separation: Test and live modes have completely separate API keys

Managing keys​

  • Copy API Key: Copy your current API key to clipboard
  • Update Expiry: Change the expiration date for your keys
  • Delete Keys: Remove keys you no longer need

Error handling​

Common authentication errors​

  • 401 Unauthorized: Invalid or missing API key
  • 429 Too Many Requests: Rate limit exceeded

Troubleshooting​

  • Verify API key is correct and active
  • Check if key is associated with the correct product
  • Ensure you're using the correct hostname for test or live mode

Best practices​

Development workflow​

  1. Start with Test Mode: Use test API keys for development
  2. Secure Storage: Store keys in a secrets manager
  3. Monitor Usage: Track API usage and performance
  4. Prepare for Production: Set up live mode when ready to launch

Security guidelines​

  • Never commit API keys to version control
  • Use different keys for different environments
  • Implement proper error handling for authentication failures
  • Monitor for unusual API usage patterns

Next steps​