Skip to main content

​
Overview

Azen supports two authentication methods:
  1. API Key Authentication - For programmatic access to the API
  2. Session Authentication - For web console access (handled automatically)
This guide focuses on API key authentication for developers integrating Azen into their applications.

​
API Key Authentication

All API requests must include an API key in the azen-api-key header.

​
Header Format

curl -X POST https://api.azen.sh/api/v1/memory \
  -H "azen-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, Azen!"}'

​
How Authentication Works

The authentication flow is implemented in authMiddleware.ts:
1

Check for session authentication

The middleware first checks for an active user session (used by the web console).
2

Extract API key from header

If no session exists, the middleware extracts the azen-api-key header from the request.
3

Verify API key

The API key is verified using Better Auth’s verifyApiKey method, which checks:
  • Key validity
  • Rate limits
  • Key expiration
  • Organization association
4

Set context variables

Upon successful verification, the middleware sets:
  • userId - The user who created the key
  • organizationId - The organization the key belongs to
  • apiKeyId - The unique key identifier

​
Authentication Errors

​
Missing API Key (401)

Error: No azen-api-key header provided 
{
  "status": "unauthorized",
  "message": "no api key",
  "code": 401
}
Solution: Include the azen-api-key header in your request.

​
Invalid API Key (403)

Error: API key is invalid, expired, or disabled 
{
  "status": "forbidden",
  "message": "Invalid API key",
  "code": 403
}
Solution: Check that your API key is:
  • Correctly copied (no extra spaces)
  • Still active and not expired
  • Associated with a valid organization

​
Rate Limited (429)

Error: API key has exceeded its rate limit 
{
  "status": "rate_limited",
  "message": "Rate limit exceeded for this API key",
  "code": 429
}
Solution: Wait for the rate limit to reset or upgrade your rate limit settings. See Rate Limits for details.

​
Security Best Practices

Never expose API keys in client-side code, public repositories, or logs.

​
Store Keys Securely

# .env file (never commit this!)
AZEN_API_KEY=your_api_key_here

​
Rotate Keys Regularly

1

Create a new API key

Generate a new key from the console dashboard
2

Update your application

Deploy the new key to your application’s environment
3

Delete the old key

Remove the old key from the console once confirmed working

​
Use Key-Specific Permissions

When creating API keys, grant only the minimum permissions needed:
  • Read-only keys for monitoring and analytics
  • Write-only keys for data ingestion services
  • Full access keys only for trusted applications
API key permissions are configured in the console when creating or editing keys.

​
Organization Context

All authenticated requests are scoped to an organization:
  • API keys are tied to a specific organization (stored in organizationId metadata)
  • Memories are isolated per organization
  • Usage tracking is aggregated by organization
  • Rate limits are enforced per organization
This ensures complete data isolation between organizations in multi-tenant deployments.

​
Testing Authentication

Test your authentication setup with a simple request: 
curl -X GET https://api.azen.sh/api/v1 \
  -H "azen-api-key: YOUR_API_KEY"
Expected response: 
{
  "status": "ok"
}

​
Next Steps

Create Memories

Start storing memories with your API key

Manage API Keys

Learn how to create and manage API keys

Rate Limits

Understand rate limiting and quotas

Error Handling

Handle authentication errors gracefully

Build docs developers (and LLMs) love

Get started for freeTalk to us