Authentication

Learn how to authenticate with the Agent Action Firewall API.

API Keys

All API requests require authentication using an API key. API keys are scoped to your organization and can have different permission levels.

Creating API Keys

1. Log in to the dashboard
2. Go to Settings > API Keys
3. Click "Create API Key"
4. Select permissions and expiration
5. Copy and securely store the key

Authentication Header

Include your API key in the X-Agent-Key header:

X-Agent-Key: YOUR_API_KEY

Agent Identification

The agent identity is determined by which API key is used — the name registered with that key in the dashboard. The SDK also sends an X-Agent-Id header for distributed tracing, but the server derives the agent from the key lookup, not from this header.

X-Agent-Key: aaf_abc123...

Complete Example

curl -X POST https://api.agentactionfirewall.com/v1/actions \
  -H "X-Agent-Key: aaf_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"tool": "http_proxy", "operation": "get", "params": {"url": "https://api.example.com"}}'

Permission Scopes

Key Types

All valid API keys start with the aaf_ prefix (e.g. aaf_abc1234...). Requests with a key that does not start with aaf_ are rejected with a 401 before hitting the database.

Agent Keys

For AI agents submitting actions. Limited to actions:write andactions:read scopes.

Admin Keys

For dashboard and administrative operations. Can have any combination of scopes.

Webhook Keys

For validating incoming webhooks. Read-only and scoped to webhook verification.

Key Security

Best Practices

• Never commit API keys to version control
• Use environment variables for key storage
• Rotate keys regularly (at least every 90 days)
• Use the minimum required scopes
• Set key expiration dates

Key Rotation

1. Create a new API key with the same scopes
2. Update your applications to use the new key
3. Verify the new key works correctly
4. Revoke the old key in the dashboard

Error Responses

401 Unauthorized

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

403 Forbidden

{
  "error": "FORBIDDEN",
  "message": "API key lacks required scope: policies:write"
}

SDK Authentication

import { AgentFirewallClient } from '@agent-action-firewall/sdk';

const client = new AgentFirewallClient({
  baseUrl: 'https://api.agentactionfirewall.com',
  apiKey: process.env.AGENT_FIREWALL_API_KEY!,
  agentId: 'my-agent',
});

// The SDK handles authentication headers automatically

MFA Recovery Codes

Human users authenticated with a Supabase JWT can manage MFA recovery codes. These routes use the Authorization: Bearer <JWT> header.

Generate Recovery Codes

Requires AAL2 (active MFA session). Returns one-time plaintext codes — store them securely.

POST /v1/mfa/recovery-codes/generate
Authorization: Bearer $SUPABASE_JWT

Check Remaining Code Count

Requires AAL2. Returns the number of unused recovery codes remaining.

GET /v1/mfa/recovery-codes/status
Authorization: Bearer $SUPABASE_JWT

Verify a Recovery Code

Requires AAL1 (password only). Validates the provided recovery code and removes active TOTP factors — use this when locked out of an authenticator app.

POST /v1/mfa/recovery-codes/verify
Authorization: Bearer $SUPABASE_JWT
Content-Type: application/json

{ "code": "XXXX-XXXX-XXXX" }

Delete Recovery Codes

Purges all recovery codes for the authenticated user. Called automatically on MFA unenrollment.

DELETE /v1/mfa/recovery-codes
Authorization: Bearer $SUPABASE_JWT

Password Reset

Human users can reset their password via the /forgot-password page in the dashboard. This sends a Supabase recovery email; clicking the link redirects to /reset-password where a new password can be set. There is no direct API endpoint — the flow is handled entirely through the Supabase Auth UI.

Next Steps

• Actions API
• Approvals API