Authentication

All API requests to Agent OTP require authentication using API keys. This guide covers how to authenticate your requests.

API Keys

API keys are used to authenticate requests from your agents. Each agent has its own API key, which is used to identify and authorize the agent.

Creating an API Key

Generate an API key using the CLI after starting your self-hosted instance:

# Create a new agent and generate API key
docker compose exec api bun run cli agent:create --name "my-assistant"

# Output:
# Agent created successfully!
# API Key: ak_live_xxxxxxxxxxxxxxxxxxxx

Important: API keys are only shown once. Store them securely in your environment variables or secrets manager.

API Key Format

API keys follow this format:

ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
└─┬──┘ └─┬─┘ └──────────────┬──────────────┘
  │     │                   │
  │     │                   └── 32-character random string
  │     └── Environment (live or test)
  └── Key type prefix

Using API Keys

Bearer Token (Recommended)

Include your API key in the Authorization header:

curl -X POST https://api.agentotp.com/v1/permissions/request \
  -H "Authorization: Bearer ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "email.send", "scope": {}}'

X-API-Key Header

Alternatively, use the X-API-Key header:

curl -X POST https://api.agentotp.com/v1/permissions/request \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"action": "email.send", "scope": {}}'

SDK Authentication

When using the SDK, pass the API key to the constructor:

import { AgentOTPClient } from '@orrisai/agent-otp-sdk';

const client = new AgentOTPClient({
  apiKey: process.env.AGENT_OTP_API_KEY!,
});

Test vs. Live Keys

Key TypePrefixPurpose
Liveak_live_Production use, counts against quotas
Testak_test_Development use, does not count against quotas

Test keys auto-approve all requests and do not send notifications. Use them for development and testing only.

Key Rotation

You can rotate API keys without downtime:

  1. Create a new API key for the agent
  2. Update your application to use the new key
  3. Verify the new key is working
  4. Revoke the old key
// Support multiple keys during rotation
const client = new AgentOTPClient({
  apiKey: process.env.AGENT_OTP_API_KEY_NEW
    || process.env.AGENT_OTP_API_KEY!,
});

Revoking Keys

Revoke compromised or unused keys immediately using the CLI:

# List agents to find the one to revoke
docker compose exec api bun run cli agent:list

# Revoke an API key
docker compose exec api bun run cli agent:revoke --id AGENT_ID

Revoked keys will receive a 401 Unauthorized response.

Rate Limits

Rate limits are configurable in your self-hosted instance. Default limits:

Limit TypeDefaultEnvironment Variable
Requests per minute60RATE_LIMIT_PER_MIN
Requests per hour1000RATE_LIMIT_PER_HOUR

Authentication Errors

StatusCodeDescription
401MISSING_API_KEYNo API key provided
401INVALID_API_KEYAPI key is malformed or doesn't exist
401EXPIRED_API_KEYAPI key has been revoked or expired

Security Best Practices

  • Never expose keys in client-side code - Only use API keys in server-side code
  • Use environment variables - Store keys in environment variables, not in code
  • Rotate keys regularly - Rotate API keys every 90 days
  • Monitor usage - Set up alerts for unusual API usage
  • Use separate keys per environment - Different keys for dev, staging, production

See Also