Authentication

Set the gateway host for curl examples:

export SANDBOX_GATEWAY_URL="${SANDBOX_GATEWAY_URL:-http://localhost:8780}"

API key (break-glass)

curl -H "X-Api-Key: dev-local-key" "$SANDBOX_GATEWAY_URL/sandbox/v1/catalog"

Set SANDBOX_API_KEY / SANDBOX_API_KEYS in Helm or infra/local/.env.stack.

KeyHive team token (multi-tenant)

Harbor and Agent Runtime can lease provider keys per namespace.

1. Create a team (admin):

curl -sS -H "X-Api-Key: dev-local-key" -H "Content-Type: application/json" \
  -d '{"namespace":"acme:proj1","keys":{"openai":"sk-..."}}' \
  "$SANDBOX_GATEWAY_URL/sandbox/v1/admin/credential-plane/teams"

2. Call APIs with Authorization: Bearer <team-token>.

Local dev tokens: KEYHIVE_DEV_TOKENS in compose (dev-token-a → acme:proj-a).

Keycloak (service-to-service)

Configure SERVICE_KC_* env vars on the gateway. Pass Authorization: Bearer <jwt> with allowed audience/client.

What is not authenticated

• Gateway /healthz (no /sandbox prefix)
• Docs at /docs (read-only; no secrets in static site)

Correlation id (x-correlation-id)

Send a stable id per eval run so logs, Cloud Trace, harbor async jobs, and Langfuse LLM traces share one key. If omitted, the gateway generates a ULID.

Full contract: Observability and correlation.

Next steps

• Observability and correlation
• Errors & limits
• Credential plane admin API