Run API Authentication

The Run API (agents-api routes under /run) authenticates requests using a Bearer token in the Authorization header. Authentication is attempted in the following priority order:

1. JWT Temp Token

Short-lived JWT tokens generated from user session cookies (e.g., via the SDK or device authorization flow). These tokens are signed with INKEEP_AGENTS_TEMP_JWT_PUBLIC_KEY.

curl -H "Authorization: Bearer eyJ..." \
  https://your-api/run/v1/chat/completions

The token payload includes tenantId, projectId, and agentId.

2. Bypass Secret

When INKEEP_AGENTS_RUN_API_BYPASS_SECRET is set, you can use this secret as the Bearer token. Requires scope headers:

curl -H "Authorization: Bearer $INKEEP_AGENTS_RUN_API_BYPASS_SECRET" \
     -H "x-inkeep-tenant-id: tenant-123" \
     -H "x-inkeep-project-id: project-456" \
     -H "x-inkeep-agent-id: agent-789" \
     https://your-api/run/v1/chat/completions

Useful for admin access, CI/CD pipelines, and internal services.

3. Database API Key

API keys created from the Manage UI and stored in the database. The key encodes scope (tenant, project, agent), so no additional headers are required.

curl -H "Authorization: Bearer ink_your_api_key" \
  https://your-api/run/v1/chat/completions

4. Team Agent Token

JWT tokens used for intra-tenant agent-to-agent delegation. These tokens specify an origin agent and target agent, enabling secure team collaboration between agents.

The token's aud (audience) claim is validated against the x-inkeep-sub-agent-id header if provided.

Development Mode

When ENVIRONMENT=development or ENVIRONMENT=test:

• Authentication is attempted but not required
• If no valid auth is found, falls back to default context
• You can specify scope via headers:

curl -H "x-inkeep-tenant-id: test-tenant" \
     -H "x-inkeep-project-id: test-project" \
     -H "x-inkeep-agent-id: test-agent" \
     http://localhost:3002/run/v1/chat/completions

If headers are omitted, defaults to test-tenant, test-project, test-agent.

Request Headers