Lamba

Before you start

Customer products should use the public auth and API hosts. The Lamba console configures applications, domains, roles, webhooks, and add-ons, but your product runtime should call only id.* and api.*.

Host responsibilities

Host	Purpose
`id.uselamba.com`	Hosted auth, OAuth/OIDC, token exchange, refresh, logout, context switch
`api.uselamba.com`	Customer profile, authorization, sessions, members, admin runtime operations

Token exchange

Public browser and mobile clients use Authorization Code + PKCE. Confidential server-side clients may use a client secret, but the secret must stay on a trusted server.

Session refresh

Refresh is allowed only when the current session contract permits it. If refresh fails with 401, restart sign-in or explicit Project context entry instead of retrying indefinitely.

Logout

Logout should clear local product state and end the relevant Lamba session state. Treat logout as an identity event that can appear in audit or webhook-driven workflows.

Context switch

Context switch converts a valid login into scoped runtime access for a Workspace, Project, and environment.

curl -X POST "$LAMBA_CUSTOMER_AUTH_BASE/v1/sessions/switch-context" \
  -H "Authorization: Bearer $CUSTOMER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<workspace-id>",
    "projectId": "<project-id>",
    "environment": "test"
  }'

Failure modes

Status	Meaning	Client behavior
`400`	Invalid request shape	Fix client request
`401`	Missing, expired, or revoked session	Refresh once or restart sign-in
`403`	Authenticated but not authorized	Hide/disable action and reload authorization
`409`	Conflicting state	Reload state before retry
`429`	Rate limited	Honor `Retry-After`

Hosted Auth Integration: /docs/quickstart/hosted-auth
Scoped Sessions: /docs/concepts/scoped-sessions
API Overview: /docs/reference/api-overview