Skip to content
Lamba
Sign In

Concepts

Request Scoping

How customer auth and API requests resolve Workspace, Project, and environment from the active session.

Customer request model

Customer products use two public hosts:

HostPurposeContext source
id.uselamba.comAuth, OIDC discovery, token exchange, refresh, logout, context switchAuth host binding and session token
api.uselamba.comProfile, memberships, authorization, admin runtime APIs, domains, webhooks, SMS add-onsScoped customer session token

Customer requests are token-scoped. Your app should not add console-only workspace or project headers to id.* or api.*.

How context is resolved

Lamba resolves the active Workspace, Project, and environment from one of these sources:

  • configured customer auth defaults on the selected auth host
  • the session returned by password, register, magic-link, phone, email verify, refresh, or context switch
  • the scoped session returned by POST /v1/sessions/switch-context
  • the management token minted by POST /connect/token with grant_type=client_credentials

OIDC signs the user in on id.*. If your application needs api.* after OIDC, exchange into a scoped customer session first:

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"
  }'

Use the returned scoped token for customer API calls.

Console setup

Use the Lamba console to configure the resources that decide request scope:

  • Project applications and redirect URIs
  • Project environment (test or prod)
  • auth and API custom-domain bindings
  • Project role catalog and membership
  • webhook endpoints and event subscriptions
  • SMS add-on state and other plan-bound capabilities

Best practices

  • Keep sandbox and production application credentials separate.
  • Keep X-Correlation-Id on customer requests for support and tracing.
  • Read /v1/me/context after login or context switch to confirm the active scope.
  • Read /v1/me/authorization before rendering privileged product actions.
  • Use management client tokens only for server-side admin automation.
  • Never infer Workspace or Project from untrusted client input without membership validation.
  • Workspace/project model: /docs/concepts/tenant-project
  • API contract: /docs/reference/api-overview
  • Error handling: /docs/reference/errors