API authentication

Server-to-server calls use a tenant API key:

Authorization: Bearer glpk_<prefix>_<secret>

• The prefix is safe to log and appears in the key list; the secret is shown once at issuance and stored hashed.
• Keys carry scopes (GET /v1/keys/scopes lists them: keys:manage, users:read, users:write, flows:read|write|run, sources:read|write, contacts:read|write, results:read, adapters:manage, webhooks:manage, branding:manage). A key acts for the whole tenant; there is no narrower scope to select per request. Your bootstrap key (issued with the tenant) has every scope.
• Issue further keys with POST /v1/keys { "name", "scopes"?, "expiresAt"? }; the plaintext is returned once; GET /v1/keys lists prefixes and status only.
• Rotation = issue a new key, then revoke the old one; revocation takes effect within 60 s.
• Keys are for your backend only. Browsers never hold an API key; GUI users get a session token instead.

Who can call what: gates

Every Engine route declares a gate: admin, tenant, or user. Gates are hierarchical (admin ⊇ tenant ⊇ user):

• The gate says who may call a route. Scopes on a tenant key say what it may do on tenant- and user-gated routes (e.g. flows:write, adapters:manage). Admin keys hold every scope; user sessions have none; a user acts as themselves inside their tenant and only on the flows, sources, contacts and lists they own (who owns what).
• A handful of routes are user-exact (GET /v1/auth/me, POST /v1/auth/logout); an API key has no session, so keys get 403 there.
• Public (no gate): /healthz, /readyz, /openapi.json, POST /v1/auth/session, GET /verify/{token}.
• Errors: no or invalid credential → 401; wrong kind for the gate or missing scope → 403.