Run API Authentication

The Run API (agents-run-api) has three authentication modes depending on your environment configuration:

Development Mode

When ENVIRONMENT=development:

• No API key required
• Must include scope headers:
  • x-inkeep-tenant-id
  • x-inkeep-project-id
  • x-inkeep-graph-id

curl -H "x-inkeep-tenant-id: tenant-123" \
     -H "x-inkeep-project-id: project-456" \
     -H "x-inkeep-graph-id: graph-789" \
     https://localhost:3003/v1/chat/completions

Standard Mode

When ENVIRONMENT≠development and INKEEP_AGENTS_RUN_API_BYPASS_SECRET is not set:

• Use API keys created from the Management UI
• No additional headers required (scope encoded in key)

curl -H "Authorization: Bearer sk_live_abc123..." \
  https://localhost:3003/v1/chat/completions

Bypass Mode

When ENVIRONMENT≠development and INKEEP_AGENTS_RUN_API_BYPASS_SECRET is set:

Option 1: Bypass Secret

• Use the bypass secret as token
• Must include scope headers

curl -H "Authorization: Bearer YOUR_BYPASS_SECRET" \
     -H "x-inkeep-tenant-id: tenant-123" \
     -H "x-inkeep-project-id: project-456" \
     -H "x-inkeep-graph-id: graph-789" \
     https://run-api.example.com/chat/completions

Option 2: Standard API Key

• Use API keys from Management UI
• Falls back to database validation

curl -H "Authorization: Bearer sk_live_xyz789..." \
  https://run-api.example.com/chat/completions

Running Multiple Instances

To run multiple Run API instances with different auth configurations:

# Instance 1: Port 3003 with bypass secret
PORT=3003 INKEEP_AGENTS_RUN_API_BYPASS_SECRET=secret123 pnpm dev

# Instance 2: Port 3004 without bypass secret
PORT=3004 pnpm dev

Security Best Practices

1. Production: Always use API keys or bypass secrets
2. Bypass Secret: Use for internal services only
3. API Keys: Rotate regularly and set expiration dates
4. Headers: Use HTTPS to protect header values in transit