DocumentationAgent Action Firewall
GitHub

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:

HTTP
X-Agent-Key: YOUR_API_KEY

Agent Identification

Include the agent ID in the X-Agent-Id header:

HTTP
X-Agent-Id: my-agent-name

Complete Example

Bash
curl -X POST https://api.agentactionfirewall.com/v1/actions \
  -H "X-Agent-Key: sk_live_abc123..." \
  -H "X-Agent-Id: customer-service-bot" \
  -H "Content-Type: application/json" \
  -d '{"tool": "http_proxy", "operation": "GET", "params": {"url": "https://api.example.com"}}'

Permission Scopes

ScopeDescription
actions:writeSubmit and manage actions
actions:readView action status and history
approvals:writeApprove or deny actions
approvals:readView pending approvals
policies:writeCreate and modify policies
policies:readView policies
audit:readAccess audit logs
admin:*Full administrative access

Key Types

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

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

403 Forbidden

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

SDK Authentication

TypeScript
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

Next Steps