Authentication¶

AMP uses API keys for programmatic access and JWT tokens for user sessions. All API requests must be authenticated.

API Keys¶

API keys are the primary authentication method for server-to-server communication.

Creating an API Key¶

curl -X POST https://api.amp.dev/v1/auth/keys \
  -H "Authorization: Bearer $EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "scopes": ["missions:read", "missions:write", "content:read"],
    "expires_in_days": 365
  }'

{
  "id": "key_2xK9mPqR4vN8sT3w",
  "name": "Production Server",
  "key": "amp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key_prefix": "amp_live_xxxx",
  "scopes": ["missions:read", "missions:write", "content:read"],
  "expires_at": "2025-01-15T00:00:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Using API Keys¶

Include your API key in the Authorization header:

curl https://api.amp.dev/v1/missions \
  -H "Authorization: Bearer amp_live_xxxxxxxxxxxxxxxxxxxx"

Key Prefixes¶

Keys have environment-specific prefixes:

Scopes¶

Scopes control what an API key can access:

Example with limited scope:

# This key can only read missions and content
curl -X POST https://api.amp.dev/v1/auth/keys \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Dashboard",
    "scopes": ["missions:read", "content:read", "analytics:read"]
  }'

Rotating Keys¶

Rotate keys without downtime using a two-phase approach:

# 1. Create new key with same scopes
curl -X POST https://api.amp.dev/v1/auth/keys/key_OLD_ID/rotate \
  -H "Authorization: Bearer $AMP_API_KEY"

{
  "old_key_id": "key_OLD_ID",
  "new_key_id": "key_NEW_ID",
  "new_key": "amp_live_new_xxxxxxxxxxxxxxxxxxxxx",
  "old_key_valid_until": "2024-01-22T10:30:00Z"
}

The old key remains valid for 7 days, giving you time to update all systems.

Revoking Keys¶

curl -X DELETE https://api.amp.dev/v1/auth/keys/key_2xK9mPqR4vN8sT3w \
  -H "Authorization: Bearer $AMP_API_KEY"

Revocation is immediate. All requests using the revoked key will return 401 Unauthorized.

JWT Tokens¶

JWT tokens are used for browser-based authentication through Clerk.

Token Flow¶

sequenceDiagram
    participant User
    participant Browser
    participant Clerk
    participant AMP API

    User->>Browser: Login
    Browser->>Clerk: Authenticate
    Clerk-->>Browser: JWT Token
    Browser->>AMP API: Request + JWT
    AMP API->>Clerk: Verify Token
    Clerk-->>AMP API: Valid
    AMP API-->>Browser: Response

Using JWT Tokens¶

curl https://api.amp.dev/v1/auth/whoami \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Refresh¶

Tokens expire after 1 hour. Refresh before expiration:

curl -X POST https://api.amp.dev/v1/auth/refresh \
  -H "Authorization: Bearer $CURRENT_TOKEN"

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-15T11:30:00Z"
}

Tenant Context¶

All API requests operate within a tenant context. API keys are scoped to a specific tenant.

Multi-Tenant Access¶

Users with access to multiple tenants can switch context:

# List accessible tenants
curl https://api.amp.dev/v1/tenants \
  -H "Authorization: Bearer $AMP_API_KEY"

# Use tenant-specific header
curl https://api.amp.dev/v1/missions \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "X-Tenant-ID: tnt_xxxxxxxxxxxxx"

Rate Limiting¶

API requests are rate limited per API key:

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1705319400

When rate limited, you'll receive:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Security Best Practices¶

Key Management¶

1. Use separate keys per environment — Don't share keys between dev/staging/prod
2. Minimize scope — Only grant permissions each key needs
3. Set expiration — Rotate keys at least annually
4. Audit regularly — Review active keys and revoke unused ones

Environment Variables¶

Store keys in environment variables, never in code:

export AMP_API_KEY="amp_live_xxxxx"

const apiKey = process.env.AMP_API_KEY;

import os
api_key = os.environ.get('AMP_API_KEY')

apiKey := os.Getenv("AMP_API_KEY")

Secret Managers¶

For production, use a secret manager:

• AWS Secrets Manager
• Google Secret Manager
• HashiCorp Vault
• 1Password Secrets Automation

Webhook Signature Verification¶

When receiving webhooks, always verify the signature:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Next Steps¶

• Your First Mission — Create and run a mission
• API Reference — Full auth endpoint documentation
• Webhooks — Receive real-time events