Authentication

• API keys - For SDK integration (recommended)
• JWT tokens - For web console access (automatic via Clerk)

Authorization: Bearer <token>

API keys (for SDK)

Generate an API key

1. Log in to console.agentsentinel.dev
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy the key immediately (shown only once)
5. Store it securely (password manager, secrets vault)

curl -X POST "$AGENT_SENTINEL_URL/api/v1/api-keys/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-agent"}'

{
  "id": "key_abc123",
  "key": "as_a1b2c3d4e5f6...",
  "key_prefix": "as_a1b2c3",
  "name": "production-agent",
  "agent_id": null,
  "scopes": ["ingest"],
  "expires_at": null,
  "created_at": "2024-12-28T10:00:00Z"
}

Agent-bound keys

curl -X POST "$AGENT_SENTINEL_URL/api/v1/api-keys/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "billing-agent-key",
    "agent_id": "billing-agent",
    "scopes": ["ingest"],
    "expires_at": "2026-12-31T00:00:00Z"
  }'

• agent_id - When set, this key can only be used to ingest logs for that agent. If a POST /ingest request presents a different agent_id (at the payload or entry level), the request is rejected with 403 and detail agent_id does not match the bound key. If the request omits agent_id entirely, the bound value is used automatically. Keys without agent_id set are unrestricted, matching prior behavior.
• Management writes - A key with agent_id set gets 403 with reason_code agent_bound_key_forbidden when it tries to change governance configuration: creating, updating, deleting or testing escalation rules and notification channels, updating compliance mappings, updating agent metadata, deleting action definitions, and reviving a kill-switch target. It can still call POST /kill-switch/kill, so an agent can always halt itself. Unbound keys and user sessions are unaffected.
• scopes - Permission scopes granted to the key. Defaults to ["ingest"].
• expires_at - Optional expiration timestamp. Once passed, the key fails verification with 401 and detail API key has expired, distinct from a revoked (deactivated) key.

Use an API key in SDK

from agent_sentinel import enable_remote_sync

enable_remote_sync(
    api_token="as_your_api_key_here",  # Use your API key
    run_id="run-001"
)

Manage API keys

curl "$AGENT_SENTINEL_URL/api/v1/api-keys/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X DELETE "$AGENT_SENTINEL_URL/api/v1/api-keys/{key_id}" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JWT tokens (for web console)

When you need a JWT

• Accessing the web console
• Making API calls from the browser
• Programmatic API access (e.g., scripts, CI/CD)

Get a JWT token

1. Log in to the web console
2. Open browser DevTools → Console
3. Run:
   await window.Clerk.session.getToken()
   
4. Copy the token (valid for 1 hour)

JWT expiration

• Web console: Tokens auto-refresh - you stay logged in
• Programmatic: Tokens expire after 1 hour - regenerate as needed

Best practices

Troubleshooting

• Verify API key is correct (starts with as_)
• Check key is still active (not revoked)
• Check key has not passed its expires_at (detail: “API key has expired”)
• Ensure you’re using Authorization: Bearer <key> header

• The key is bound to a specific agent_id; the ingest payload (or an entry within it) specified a different agent_id
• Either omit agent_id in the request (the bound value is used automatically) or use a key that isn’t bound to an agent

• Keys may take up to 30 seconds to propagate
• Verify you copied the full key including as_ prefix
• Test with a simple API call to verify

See also

• Quickstart - Get your first API key and connect to the platform
• Settings - Manage API keys in the web console