Managing API Keys

Overview

API keys are the primary authentication method for programmatic access to Azen. Each key is scoped to an organization and can be configured with rate limits, expiration, and permissions.

Creating API Keys

Access the console

Navigate to API keys

Go to Settings → API Keys in the sidebar.

Create new key

Click Create API Key and configure your key settings.

Copy and store

Copy the API key immediately - it won’t be shown again. Store it securely in your environment variables or secrets manager.

API keys are shown only once during creation. If you lose a key, you’ll need to create a new one and delete the old key.

API Key Structure

API keys are stored with the following fields in the database schema:

Key Fields

From packages/db/src/db/schema.ts:

export const apikey = pgTable("apikey", {
  id: text("id").primaryKey(),
  name: text("name"),                    // Human-readable key name
  start: text("start"),                  // First chars for identification
  prefix: text("prefix"),                // Key prefix (e.g., "az_live")
  key: text("key").notNull(),            // Hashed key value
  userId: text("user_id").notNull(),     // Creator/owner user
  organizationId: text("organization_id"), // Owning organization
  
  // Rate limiting
  refillInterval: integer("refill_interval"),
  refillAmount: integer("refill_amount"),
  lastRefillAt: timestamp("last_refill_at"),
  rateLimitEnabled: boolean("rate_limit_enabled").default(true),
  rateLimitTimeWindow: integer("rate_limit_time_window").default(60000),
  rateLimitMax: integer("rate_limit_max").default(60),
  requestCount: integer("request_count").default(0),
  remaining: integer("remaining"),
  
  // Status and tracking
  enabled: boolean("enabled").default(true),
  lastRequest: timestamp("last_request"),
  expiresAt: timestamp("expires_at"),
  createdAt: timestamp("created_at").defaultNow().notNull(),
  updatedAt: timestamp("updated_at").notNull(),
  
  // Advanced
  permissions: text("permissions"),
  metadata: json("metadata"),
});

Configuring Rate Limits

Token Bucket Algorithm

Azen uses a token bucket rate limiting algorithm:

rateLimitMax: Maximum requests in the time window (default: 60)
rateLimitTimeWindow: Time window in milliseconds (default: 60000 = 1 minute)
refillInterval: How often tokens refill (optional)
refillAmount: How many tokens to add on refill (optional)

Rate Limit Examples

Standard Rate Limit (60 req/min)

{
  "rateLimitEnabled": true,
  "rateLimitMax": 60,
  "rateLimitTimeWindow": 60000
}

Allows 60 requests per minute. Exceeding this returns HTTP 429.

High Throughput (1000 req/min)

{
  "rateLimitEnabled": true,
  "rateLimitMax": 1000,
  "rateLimitTimeWindow": 60000
}

Suitable for production applications with high traffic.

Burst Allowance with Refill

{
  "rateLimitEnabled": true,
  "rateLimitMax": 100,
  "rateLimitTimeWindow": 60000,
  "refillInterval": 10000,
  "refillAmount": 20
}

Allows bursts up to 100 requests, with 20 tokens added every 10 seconds.

No Rate Limit

{
  "rateLimitEnabled": false
}

Disables rate limiting entirely (not recommended for production).

Rate limit configuration is set during key creation and can be updated from the console.

Key Permissions

API keys can be scoped with specific permissions (stored in the permissions field):

memory.read: List and retrieve memories
memory.write: Create new memories
memory.delete: Delete memories
usage.read: View usage statistics

Permission scoping is enforced in the console. The API currently assumes full permissions for valid keys.

Key Expiration

Set an expiration date for temporary or time-limited keys:

{
  expiresAt: "2024-12-31T23:59:59Z"
}

Expired keys return HTTP 403 with message “Invalid API key”.

Use short-lived keys for demos, testing, or third-party integrations that require temporary access.

Key Metadata

Store additional context about keys using the metadata JSON field:

{
  "metadata": {
    "organizationId": "org_123",
    "environment": "production",
    "service": "chatbot-api",
    "createdBy": "[email protected]"
  }
}

Metadata is not enforced by the API but useful for:

Tracking key usage context
Auditing key creation
Identifying keys in logs

Monitoring API Keys

Track Usage

Monitor key usage from the console:

Total requests: Lifetime request count
Last request: Timestamp of most recent API call
Remaining tokens: Current rate limit token balance

View Activity

See detailed usage metrics:

curl -X GET https://api.azen.sh/api/v1/usage \
  -H "azen-api-key: YOUR_API_KEY"

Returns usage statistics for your organization over the last 30 days. See Usage Tracking for details.

Revoking API Keys

Identify the key

Find the key to revoke in the console’s API Keys list.

Disable or delete

Disable: Set enabled to false (key can be re-enabled later)
Delete: Permanently remove the key from the database

Verify

Confirm that API requests with the revoked key return HTTP 403.

Deleting a key is permanent and cannot be undone. Disabled keys can be re-enabled if needed.

Key Rotation Best Practices

Regular Rotation

Rotate keys every 90 days:

Create new key

Generate a new API key with identical permissions and rate limits.

Update applications

Deploy the new key to all services using the old key.

Monitor

Verify that the old key shows no recent activity (check lastRequest timestamp).

Delete old key

Once confirmed, delete the old key from the console.

Emergency Rotation

If a key is compromised:

Immediately disable the compromised key
Create a new key with different settings
Update all applications ASAP
Audit logs to check for unauthorized access
Delete the compromised key once migration is complete

Troubleshooting

Key Not Working (403)

Possible causes:

Key is disabled (enabled: false)
Key has expired (expiresAt in the past)
Key is not associated with a valid organization
Key was deleted

Solution: Create a new key or check key status in console.

Rate Limit Exceeded (429)

{
  "status": "rate_limited",
  "message": "Rate limit exceeded for this API key",
  "code": 429
}

Solution:

Wait for rate limit to reset
Implement exponential backoff
Request higher rate limits from console

Key Not Found in Requests

Symptom: HTTP 401 “no api key” Solution: Ensure you’re sending the azen-api-key header:

curl -H "azen-api-key: YOUR_KEY" https://api.azen.sh/api/v1/memory

Security Recommendations

Use Environment Variables

Never hardcode keys in source code. Use environment variables or secrets managers.

Separate Keys per Environment

Use different keys for development, staging, and production environments.

Rotate Regularly

Rotate keys every 90 days or after team member departures.

Monitor Activity

Regularly review key usage to detect anomalies or compromised keys.

Scope Permissions

Grant only the minimum permissions needed for each key’s purpose.

Set Expiration

Use short-lived keys for temporary access or third-party integrations.

Next Steps

Authentication Guide

Learn how to use API keys in requests

Rate Limits

Understand rate limiting in detail

Usage Tracking

Monitor API usage and quotas

Organizations

Understand organization-based access control

Get Started

Core Concepts

Guides

Managing API Keys

Overview

Creating API Keys

API Key Structure

Key Fields

Configuring Rate Limits

Token Bucket Algorithm

Rate Limit Examples

Key Permissions

Key Expiration

Key Metadata

Monitoring API Keys

Track Usage

View Activity

Revoking API Keys

Key Rotation Best Practices

Regular Rotation

Emergency Rotation

Troubleshooting

Key Not Working (403)

Rate Limit Exceeded (429)

Key Not Found in Requests

Security Recommendations

Use Environment Variables

Separate Keys per Environment

Rotate Regularly

Monitor Activity

Scope Permissions

Set Expiration

Next Steps

Authentication Guide

Rate Limits

Usage Tracking

Organizations

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Overview

​Creating API Keys

​API Key Structure

​Key Fields

​Configuring Rate Limits

​Token Bucket Algorithm

​Rate Limit Examples

​Key Permissions

​Key Expiration

​Key Metadata

​Monitoring API Keys

​Track Usage

​View Activity

​Revoking API Keys

​Key Rotation Best Practices

​Regular Rotation

​Emergency Rotation

​Troubleshooting

​Key Not Working (403)

​Rate Limit Exceeded (429)

​Key Not Found in Requests

​Security Recommendations

Use Environment Variables

Separate Keys per Environment

Rotate Regularly

Monitor Activity

Scope Permissions

Set Expiration

​Next Steps

Authentication Guide

Rate Limits

Usage Tracking

Organizations

Build docs developers (and LLMs) love

Overview

Creating API Keys

API Key Structure

Key Fields

Configuring Rate Limits

Token Bucket Algorithm

Rate Limit Examples

Key Permissions

Key Expiration

Key Metadata

Monitoring API Keys

Track Usage

View Activity

Revoking API Keys

Key Rotation Best Practices

Regular Rotation

Emergency Rotation

Troubleshooting

Key Not Working (403)

Rate Limit Exceeded (429)

Key Not Found in Requests

Security Recommendations

Next Steps