Authentication and access

RunMat Server authenticates interactive users with OIDC tokens and supports scoped headless credentials for CLI, CI, and service integrations. Authentication establishes identity; organization role, project membership, and policy determine authorization.

Interactive requests validate the token issuer, audience, signature, lifetime, and subject, then map the external identity to an internal user. Headless API keys map to service identities and should be scoped, rotated, and stored in a secret manager outside project source and notebook output.

Roles include organization-level owner and administrator responsibilities plus member or viewer access according to the active policy. Project membership can narrow access further. SSO and SCIM, when enabled for a deployment, manage enterprise identity lifecycle. Server still authorizes the resulting identity for each resource.

For an access failure, distinguish 401 Unauthorized (missing or invalid authentication) from 403 Forbidden (authenticated but not permitted). Confirm the selected organization and project as well as the credential itself. Audit credential creation, rotation, role changes, and revocation.

Interactive login

Clients send an email and client kind to POST /auth/resolve. Server selects hosted identity or the organization's SSO route. Web clients follow the returned redirect. Desktop and CLI use public-client PKCE configuration and a loopback callback. After login, GET /auth/me returns the mapped user, organizations, memberships, and preferences.

Desktop opens the system browser for authentication. A short-lived bridge may associate first-party website activity with the authenticated Desktop identity. An authenticated consume operation completes that association. Login can finish if analytics linking fails.

API keys

Headless keys use the form rk.<environment>.<key-id>.<secret>. Server stores the key ID and a peppered HMAC of the secret. The secret is shown once. Create separate keys for CI, workers, and integrations; scope a key to one project whenever possible. Record its owner, purpose, expiration, and rotation date.

export RUNMAT_SERVER_URL=https://api.example.runmat
export RUNMAT_API_KEY='rk.production.…'
export RUNMAT_PROJECT_ID='project-id'

Store these values in the CI or deployment secret manager and mask them in logs. To rotate, deploy a replacement, verify it, then revoke the old key.

Request context and authorization

Organization roles cover tenant administration: owner, admin, member, and viewer. Project roles grant project read or write access. The authenticated request context contains identity, authentication kind, organization, optional project, request and trace IDs, and trusted client-IP resolution. Domain handlers receive this context from the auth pipeline.

SSO activation requires verified domains and a successful test login. SCIM, when enabled, manages user and group lifecycle. Provisioned users still pass normal organization, project, and feature-policy checks.

Access errors

• 401: check expiry, issuer, audience, JWKS/signature, API-key environment, and revocation.
• 403: check organization selection, role, project membership, project scope, and feature policy.
• 429: respect retry guidance and inspect the applicable rate-limit key.
• Wrong identity provider: check domain verification and the active SSO connection.
• Browser login works but Desktop fails: compare client kind, callback URI, PKCE state, and configured application/API origins.