Skip to main content

Authentication and key scopes

This reference describes Talon's current auth model across gateway traffic, tenant APIs, and admin/control-plane endpoints.

Key types​

Key typeSourcePrimary useHeader
Tenant keytalon.config.yaml -> gateway.callers[].tenant_keyAuthenticate gateway callers and tenant-scoped API accessAuthorization: Bearer <tenant_key>
Admin keyTALON_ADMIN_KEY env varAuthenticate admin/control-plane + dashboard/metricsX-Talon-Admin-Key: <key> (preferred), Authorization: Bearer <key> (fallback)

Notes:

  • tenant_key is configured per caller and maps to a tenant_id.
  • TALON_ADMIN_KEY is server-wide.

Endpoint-to-key matrix​

Endpoint familyAccepted authScope
/v1/proxy/...Tenant key (bearer)Gateway data plane (caller-specific policy)
Tenant-only write paths (/v1/agents/run, /v1/chat/completions, /mcp, /mcp/proxy)Tenant key (bearer)Tenant-scoped execution
Tenant-or-admin read paths (/v1/evidence*, /v1/status, /v1/costs*, /v1/memory*, /v1/triggers*, /v1/plans/pending, /v1/plans/{id})Tenant key (bearer) or admin keyTenant visibility for tenant keys; cross-tenant admin visibility for admin key
Admin-only paths (/v1/plans/{id}/approve, /v1/plans/{id}/reject, /v1/plans/{id}/modify, /v1/memory/{agent_id}/approve, /v1/secrets*, /v1/policies*, /v1/dashboard/*, /v1/copaw/*)Admin keyControl-plane actions
Operational control plane (/v1/runs*, /v1/overrides*, /v1/tool-approvals*)Admin keyRun management, tenant overrides, tool approval gates
Gateway dashboard + metrics (/gateway/dashboard, /api/v1/metrics, /api/v1/metrics/stream)Admin keyOperational dashboards and telemetry streams

Practical rules​

  • Use a tenant key for normal tenant workloads, including POST /v1/agents/run.
  • Use TALON_ADMIN_KEY for admin/reviewer/operator actions and all dashboard/metrics endpoints.
  • Prefer X-Talon-Admin-Key for admin calls; bearer fallback is accepted.

BYOK in quickstart mode (dev-only)​

talon serve --proxy-quickstart adds a scoped exception for upstream authentication:

  • Host-root requests (/v1/chat/completions, /v1/responses) forward the caller bearer token to the upstream provider.
  • If the caller bearer is missing, Talon falls back to OPENAI_API_KEY.
  • This does not replace tenant-key/admin-key authentication for Talon control-plane and tenant APIs.

Evidence distinction:

  • upstream_key_fingerprint identifies forwarded upstream key material safely.
  • secrets_accessed remains reserved for Talon vault reads.

Common confusion​

"Tenant key returns 401 on /v1/evidence or other tenant-or-admin paths"​

When talon serve is run without --gateway (and without a gateway: block in config), no tenant keys are loaded. Tenant-or-admin read paths (/v1/evidence, /v1/status, etc.) then accept only the admin key (X-Talon-Admin-Key or Bearer). Use the admin key for evidence and status when running a minimal server without the gateway.

"My caller key works on /v1/proxy but fails on admin endpoints"​

Expected behavior. Caller/tenant keys are not admin keys.

Quick checks:

# Tenant-key path
curl -i -H "Authorization: Bearer <tenant_key>" http://localhost:8080/v1/status

# Admin-only path
curl -i -H "X-Talon-Admin-Key: <admin_key>" http://localhost:8080/v1/secrets

Production guidance​

  • Issue distinct tenant keys per tenant/integration.
  • Keep tenant keys and admin keys separate.
  • Rotate tenant keys in gateway.callers entries (tenant_key) and rotate TALON_ADMIN_KEY through your secret manager/deploy workflow.