Skip to main content
The Azen Memory API uses API keys for authentication. All API requests must include a valid API key in the request headers.

​
API Key Format

API keys are passed via the azen-api-key header: 
azen-api-key: your_api_key_here

​
Authentication Flow

The authentication middleware processes requests in the following order:
  1. Session Authentication - Checks for an active user session (for web dashboard)
  2. API Key Authentication - Validates the azen-api-key header

​
API Key Validation

When using API key authentication:
  1. The middleware extracts the API key from the azen-api-key header
  2. The key is verified against the authentication service
  3. If valid, the request context is populated with:
    • userId - The user who created the API key
    • apiKeyId - The unique identifier of the API key
    • organizationId - The organization the API key belongs to

​
Making Authenticated Requests

​
Example: Create a Memory

curl -X POST https://api.azen.sh/api/v1/memory \
  -H "Content-Type: application/json" \
  -H "azen-api-key: your_api_key_here" \
  -d '{
    "text": "I love hiking in the mountains"
  }'

​
Authentication Errors

​
401 Unauthorized

Returned when the azen-api-key header is missing: 
{
  "status": "unauthorized",
  "message": "no api key",
  "code": 401
}

​
403 Forbidden

Returned when the API key is invalid or disabled: 
{
  "status": "forbidden",
  "message": "Invalid API key",
  "code": 403
}
This error can occur when:
  • The API key doesn’t exist
  • The API key is disabled
  • The API key has expired
  • The API key is missing required metadata (organizationId, userId)

​
429 Rate Limited

Returned when the API key has exceeded its rate limit: 
{
  "status": "rate_limited",
  "message": "Rate limit exceeded for this API key",
  "code": 429
}
See Rate Limits for more information.

​
API Key Management

API keys are managed through the Azen dashboard at https://azen.sh. Each API key belongs to an organization and can be:
  • Named - Assign descriptive names to identify keys
  • Enabled/Disabled - Toggle key activation status
  • Rate Limited - Configure custom rate limits per key
  • Expired - Set expiration dates for temporary access
  • Tracked - Monitor usage statistics and request counts
API keys are organization-scoped. All memories and operations performed with an API key belong to the key’s organization.

​
Security Best Practices

Never expose your API keys in client-side code, public repositories, or version control systems.
  1. Store keys securely - Use environment variables or secret management services
  2. Rotate keys regularly - Create new keys and revoke old ones periodically
  3. Use different keys - Separate keys for development, staging, and production
  4. Monitor usage - Review API key activity in the dashboard regularly
  5. Set expiration dates - Use time-limited keys for temporary integrations
  6. Enable rate limiting - Protect against accidental abuse or compromised keys

​
Next Steps

Rate Limits

Learn about API rate limiting and token bucket algorithm

Build docs developers (and LLMs) love

Get started for freeTalk to us