Operator Auth + Token Runbook

This runbook is the canonical operator contract for authentication in DriftGate V4.

Auth Modes

Human runtime operator

• Login: driftgate login --api-base <url>
• Credential: bearer session token
• Valid surfaces: runtime (session, execute)

Machine admin operator

• Token source: Access Control -> Service Account -> Create Token
• Credential: x-driftgate-api-key: <dgk_...>
• Valid surfaces: admin/config (policies, routes, connectors, secrets, webhooks, access-control ops)

Token Prefixes

• dg_sa_* -> service-account identifier (never a secret)
• dgk_* -> service-account token secret (valid API-key credential)
• Bearer token -> runtime session credential

Device Login Bootstrap

• CLI first checks AUTH0_DOMAIN + AUTH0_CLIENT_ID from env.
• If unset, CLI discovers metadata from GET /v4/auth/device-config on selected --api-base.
• If discovery fails, set env vars explicitly and retry.

Expected Failure Modes

• dg_sa_* in DRIFTGATE_API_KEY -> invalid credential type.
• dgk_* against runtime session/execute -> rejected (missing session token / AUTH_INVALID).
• Session token against admin-only mutation without role/scope -> forbidden.

Internal Admin Boundary

• admin.driftgate.ai is DriftGate internal.
• Customer workspace roles in app.driftgate.ai do not grant internal admin access.

Validation Checklist

1. Create service account in Access Control.
2. Mint token and copy dgk_* secret once.
3. Run driftgate policies list --workspace <workspaceId> with DRIFTGATE_API_KEY.
4. Run driftgate routes list --workspace <workspaceId> with DRIFTGATE_API_KEY.
5. Revoke token and verify subsequent calls fail.
6. Use driftgate login and verify runtime session/execute still works with bearer session auth.