GUI authentication

Available. The token flow below is live (POST /v1/users/{id}/session-tokens, POST /v1/session-tokens for a tenant session, POST /v1/auth/session, GET /v1/auth/me, POST /v1/auth/logout). OIDC is still planned.

Growth Lab has no username/password login. Identity is your platform’s job: you decide who may open Growth Lab, then mint that user a short-lived session token with your API key and hand it to the GUI. The GUI exchanges it with the Engine for an HttpOnly session cookie.

Endpoints

Method	Path	Auth	Purpose
`POST`	`/v1/users/{id}/session-tokens`	API key (`users:write`)	Mint a token for one of your users. Optional body `{ "ttlSeconds": 300 }` (min 30, max 900). Response includes the token once and `expiresAt`.
`POST`	`/v1/session-tokens`	API key (no extra scope)	Mint a tenant session token; the GUI acts as the tenant. Frozen to the minting key’s scopes. Same exchange as a user token.
`GET`	`/v1/users/{id}/session-tokens`	API key (`users:write`)	List a user’s tokens with `status` pending / consumed / expired (tokens themselves are never returned).
`DELETE`	`/v1/session-tokens/{tokenId}`	API key (`users:write`)	Revoke a pending token.
`POST`	`/v1/auth/session`	none (token in body)	Exchange `{ "kind": "session-token", "token": "…" }` for the session cookie; returns the same `Me` payload as `/me`. Single-use; expired/used/revoked tokens → `401`.
`GET`	`/v1/auth/me`	cookie	`{ kind: "user" \| "tenant", user, tenant, session }`. `user` is `null` for tenant sessions.
`POST`	`/v1/auth/logout`	cookie	Revoke the current session and clear the cookie.
`GET` / `DELETE`	`/v1/auth/sessions[/{id}]`	cookie	List / revoke the caller’s sessions (your user’s, or the tenant’s user-less sessions).

Two ways to deliver the token

Embedded (recommended): your host page sends init with the credential; see Embedding.
Standalone: link or redirect the user to https://<gui-host>/session?token=…; the GUI exchanges the token and continues to its home page.

Tokens are single-use and expire in minutes: mint one per page load, never store or reuse them, and never expose your API key to the browser. A user session can call user-gated routes (flows, sources, contacts, results). A tenant session (Me.kind === "tenant") can also call tenant-gated surfaces the minting key was scoped for (branding, adapters, keys). Bare API keys still belong on your backend.

Third-party cookies

The session cookie ge_session is Secure; HttpOnly; SameSite=None; Partitioned, so it works when the GUI is embedded cross-site. Sessions last 12 h by default and are revocable server-side. Safari may prompt via the Storage Access API on first use.

Later: OIDC

For tenants with an identity provider, a credential.kind of "oidc-id-token" is reserved: the Engine would verify the id-token against your registered issuer and map its sub to a user’s tenantKey. Not available yet.