Authentication & API Keys

AgentBackend uses API keys (Bearer tokens) for authentication. Every API request must include a valid key in the Authorization header.

Overview

Creating API Keys

Create API keys from the AgentBackend console under Settings → API Keys, or programmatically via the REST API.

curl -X POST https://api.agentbackend.ai/v1/api-keys \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "production-key"}'

{
  "id": "key_abc123",
  "name": "production-key",
  "key": "ak_live_xxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-03-27T10:00:00Z"
}

Using API Keys

Include your API key as a Bearer token in the Authorization header of every request.

curl https://api.agentbackend.ai/v1/agents \
  -H "Authorization: Bearer ak_your_api_key"

from agentbackend import AgentBackend

ab = AgentBackend("ak_your_api_key")

# Or use an environment variable (recommended)
import os
ab = AgentBackend(os.environ["AGENTBACKEND_API_KEY"])

import { AgentBackend } from "agentbackend";

// Option 1: Direct key (for quick testing only)
const ab = new AgentBackend("ak_your_api_key");

// Option 2: Environment variable (recommended for production)
// const ab = new AgentBackend(process.env.AGENTBACKEND_API_KEY);

Managing Keys

List all active keys or delete a key when it is no longer needed.

curl https://api.agentbackend.ai/v1/api-keys \
  -H "Authorization: Bearer ak_..."

curl -X DELETE https://api.agentbackend.ai/v1/api-keys/:key_id \
  -H "Authorization: Bearer ak_..."

Key Scopes

Each API key grants full access to all resources under the associated tenant. This includes agents, knowledge, data store, sessions, schedules, and billing.

Tenant Isolation

Each API key belongs to exactly one tenant. Row-level security ensures that requests can only access resources owned by the authenticated tenant.

• •Agents created by one tenant are invisible to all other tenants
• •Knowledge documents and data store schemas are fully isolated
• •Session history is scoped to the tenant and cannot be accessed cross-tenant
• •API keys cannot be used to access or modify another tenant's resources

Rate Limits

Rate limits are applied per API key. When exceeded, the API returns a 429 Too Many Requests status with a Retry-After header.

Best Practices

• •Never commit keys to version control — use environment variables or a secrets manager instead
• •Use separate keys per environment — create distinct keys for development, staging, and production
• •Rotate keys regularly — delete old keys and create new ones on a regular schedule
• •Revoke compromised keys immediately — if a key is exposed, delete it from the console and create a replacement
• •Name keys descriptively — use names like "production-backend" or "staging-ci" to track usage

# .env
AGENTBACKEND_API_KEY=ak_live_xxxxxxxxxxxxxxxxxxxx

# Never commit this file to version control
# Add .env to your .gitignore