Authentication

Authenticate your API requests

API Keys

All Agent Diff API requests require authentication via an API key.

Header Format

X-API-Key: ad_live_sk_...

Example Request

curl -X GET https://api.agentdiff.dev/api/platform/health \
  -H "X-API-Key: ad_live_sk_3dqKGDx1QkqFw7RzPSfhrzMs..."

Getting an API Key

Hosted

1. Sign up at agentdiff.dev
2. Go to your dashboard
3. Navigate to API Keys
4. Click Create New Key
5. Copy and store your key securely

API keys are shown only once. Store them securely in environment variables.

Self-Hosted

cd ops
make reissue-key

This creates a development API key and prints it to console.

For production, create keys directly in the database:

INSERT INTO api_keys (key_id, key_hash, user_id, created_at)
VALUES ('abc123', 'hashed_secret', 'user-id', NOW());

Using API Keys in SDKs

Python

from agent_diff import AgentDiff, PythonExecutorProxy

# Via environment variable (recommended)
# export AGENT_DIFF_API_KEY="ad_live_sk_..."
# export AGENT_DIFF_BASE_URL="https://api.agentdiff.dev"
client = AgentDiff()
executor = PythonExecutorProxy(env.environmentId)  # Also uses env vars!

# Or explicit
client = AgentDiff(api_key="ad_live_sk_...")

TypeScript

import { AgentDiff } from 'agent-diff';

// Via environment variable (recommended)
// export AGENT_DIFF_API_KEY="ad_live_sk_..."
const client = new AgentDiff();

// Or explicit
const client = new AgentDiff({ apiKey: 'ad_live_sk_...' });

Security Best Practices

Use environment variables

Never hardcode API keys in your source code:

# .env file (add to .gitignore!)
AGENT_DIFF_API_KEY=ad_live_sk_...
AGENT_DIFF_BASE_URL=https://api.agentdiff.dev

from agent_diff import AgentDiff

# SDK automatically reads from env vars
client = AgentDiff()

Rotate keys regularly

Create new keys periodically and delete old ones.

Use separate keys per environment

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

Monitor key usage

Review API usage in your dashboard to detect unauthorized access.

Error Responses

Missing API Key

{
  "ok": false,
  "error": "not_authed",
  "detail": "API key required"
}

Invalid API Key

{
  "ok": false,
  "error": "not_authed",
  "detail": "Invalid API key"
}

Expired API Key

{
  "ok": false,
  "error": "not_authed",
  "detail": "API key has expired"
}

Rate Limiting

API keys have daily rate limits:

Resource	Daily Limit
Environments created	200
API requests	2,000

When rate limited, you’ll receive:

{
  "valid": false,
  "reason": "daily environment limit reached",
  "limit": 200,
  "current": 200
}

Need higher limits? Contact me at [e-mail]