Authentication
Authentication Overview
JWT, API key, and runtime-token authentication modes in the gateway.
The gateway supports three authentication modes, each optimized for a different caller type.
Authentication Methods
| Method | Format | Use Case |
|---|---|---|
| JWT | Authorization: Bearer <jwt> | Human-facing app flows and admin operations |
| API Key | X-Api-Key: gk_xxx (+ JWT or X-User-Id) | Server-to-server trust for runtimes and integrations |
| Runtime Token | Authorization: Bearer art_... (or X-Api-Key: art_...) | First-party registered agent runtime identity |
When to Use Each
JWT Authentication
Use JWT for human-initiated operations:
- Logging into the dashboard
- Managing agents, credential providers, and API keys
- Invoking agents from the frontend
- Viewing audit logs and confirmations
API Key Authentication
Use API keys for machine-to-machine communication:
- Calling MCP endpoints from trusted backend services
- Credential resolve/check flows
- Service integrations that need scoped gateway access
Runtime Token Authentication (art_)
Use runtime tokens for registered first-party agents:
- Issued once at agent creation (and on token rotation)
- Validates agent identity directly
- Works with
X-Gateway-Session-Tokento preserve end-user context in callback flows
Reference Links
- Auth and pairing APIs: /docs/api-reference/auth
- API key management APIs: /docs/api-reference/api-keys
- MCP endpoints auth behavior: /docs/api-reference/mcp-proxy