Lamba

Choose this when

Use this page when your product backend needs to call Lamba public customer APIs for profile, memberships, authorization, admin runtime operations, domains, webhooks, or SMS add-ons.

The public surface is split by host:

Host	Use for
`https://test.id.uselamba.com` / `https://id.uselamba.com`	Auth, OIDC, tokens, refresh, logout, session context
`https://test.api.uselamba.com` / `https://api.uselamba.com`	Customer self-service and admin runtime APIs

Before you start

Decide which token model your request uses:

Token model	Use for	Can call
Customer session token	Actions by a signed-in customer	`/v1/me/` and allowed `/v1/admin/` routes
Management client token	Server-side automation without a human session	`/v1/admin/*` only

Customer self-service routes under /v1/me/* require a customer user session. Management clients are for admin automation and must stay server-side.

Get credentials from Console

Credentials and configuration values
Value	Console source	Env var	Used for
Workspace ID	Top Workspace selector	`LAMBA_WORKSPACE_ID`	Session context and management client binding
Project ID	Top Project selector	`LAMBA_PROJECT_ID`	Project runtime scope for auth, roles, admin routes, domains, and webhooks
Environment	Console environment badge	`LAMBA_ENV`	Keeps sandbox and production auth/API data separate
App Client ID	Integration > App Clients > App client	`LAMBA_CLIENT_ID`	Hosted auth and OIDC Authorization Code + PKCE
Management Client ID	Integration > App Clients > Management client	`LAMBA_MANAGEMENT_CLIENT_ID`	Server-side `client_credentials` automation
Management Client secretSecret	Integration > App Clients > Create or Rotate secret	`LAMBA_MANAGEMENT_CLIENT_SECRET`	Server-side `client_credentials` token exchange

Configure environment variables

LAMBA_CUSTOMER_AUTH_BASE=https://test.id.uselamba.com
LAMBA_CUSTOMER_API_BASE=https://test.api.uselamba.com
LAMBA_WORKSPACE_ID=<workspace-id>
LAMBA_PROJECT_ID=<project-id>
LAMBA_ENV=test
LAMBA_MANAGEMENT_CLIENT_ID=<management-client-id>
LAMBA_MANAGEMENT_CLIENT_SECRET=<management-client-secret>

Use production hosts only with production Workspace, Project, App Client, and webhook credentials.

Make the first request

For a signed-in customer, first get or refresh a customer session token from id.*, then call api.*.

GEThttps://test.api.uselamba.com/v1/me/context

Auth: Authorization: Bearer <customer-session-token>
Used for: Confirms the current user, Workspace, Project, environment, session, and roles

curl "$LAMBA_CUSTOMER_API_BASE/v1/me/context" \
  -H "Authorization: Bearer $CUSTOMER_SESSION_TOKEN" \
  -H "X-Correlation-Id: $(uuidgen)"

For server-side automation, create a management token:

POSThttps://test.id.uselamba.com/connect/token

Auth: Confidential management client credentials
Used for: Creates a short-lived token for `/v1/admin/*` automation

curl -fsS "$LAMBA_CUSTOMER_AUTH_BASE/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$LAMBA_MANAGEMENT_CLIENT_ID" \
  -d "client_secret=$LAMBA_MANAGEMENT_CLIENT_SECRET" \
  -d "workspaceId=$LAMBA_WORKSPACE_ID" \
  -d "projectId=$LAMBA_PROJECT_ID" \
  -d "environment=$LAMBA_ENV" \
  -d "scope=customer.members.read customer.webhooks.read"

Then call admin routes:

curl "$LAMBA_CUSTOMER_API_BASE/v1/admin/members?limit=20" \
  -H "Authorization: Bearer $MANAGEMENT_ACCESS_TOKEN"

Request fields

Public customer API requests normally use bearer token scope:

Authorization: Bearer <customer-session-token-or-management-token>
X-Correlation-Id: <uuid-optional>

Do not send these internal console headers from customer apps:

X-Tenant-Id: ...
X-Project-Id: ...
X-Environment: ...

Management token request fields:

Request and response fields
Field	Type	Required	Meaning	Notes
`grant_type`	string	Required	OAuth grant for the token request.	Use `client_credentials` for management clients.
`client_id`	string	Required	Management Client ID from `Integration > App Clients`.	-
`client_secret`	string	Required	Management Client secret shown only when created or rotated.	Keep server-side only.
`workspaceId`	string	Required	Workspace that owns the management request.	-
`projectId`	string	Required	Project runtime scope for admin operations.	-
`environment`	test \| prod	Required	Environment for the scoped admin token.	-
`scope`	space-separated string	Optional	Requested admin scopes.	The issued token is still limited by the management client contract.

Profile update request fields:

Request and response fields
Field	Type	Required	Meaning	Notes
`username`	string	Optional	Customer-visible username.	-
`displayName`	string	Optional	Human-readable name shown in your product UI.	-
`bio`	string	Optional	Profile biography.	-
`headline`	string	Optional	Short profile headline.	-
`isPublicProfileEnabled`	boolean	Optional	Whether public profile visibility is enabled.	-
`links`	object \| array	Optional	Customer profile links.	At least one profile field is required in a PATCH body.

Response fields

Management token response:

Request and response fields
Field	Type	Required	Meaning	Notes
`access_token`	string	Required	Bearer token for `/v1/admin/*` automation.	-
`token_type`	string	Required	Token type.	Use as `Authorization: Bearer <access_token>`.
`expires_in`	number	Required	Token lifetime in seconds.	-
`scope`	string	Optional	Issued scope string.	-
`expires_at`	ISO-8601 datetime	Required	Absolute token expiry timestamp.	-

GET /v1/me/context response:

Request and response fields
Field	Type	Required	Meaning	Notes
`user`	object	Required	Signed-in Lamba User.	Includes `id`, `email`, `username`, `displayName`, verification fields, and avatar URL when available.
`activeWorkspace`	object \| null	Optional	Workspace selected by the scoped session.	-
`activeProject`	object \| null	Optional	Project and environment selected by the scoped session.	-
`membership`	object \| null	Optional	Current Project membership context.	-
`roleKeys`	string[]	Required	Runtime Project roles on the active session.	-
`session`	object	Required	Current session metadata such as session ID, last seen time, MFA state, and AMR.	-

Self-service response surfaces:

Endpoint	Response shape	Use for
`GET /v1/me/memberships`	`{ items, nextCursor }`	Workspace/Project membership list
`GET /v1/me/authorization`	`{ roleKeys, effectivePermissions, permissionSources, isProjectAdmin }`	Feature visibility and authorization checks
`GET /v1/me/security`	`{ emailVerified, phoneVerified, mfaRequired, mfaEnrolled, mfaSatisfied, availableFactors, lastLoginAt }`	Security settings and sign-in state
`GET /v1/me/linked-identities`	`{ password, magicLink, phone, socialProviders }`	Connected sign-in methods
`GET /v1/me/profile`	profile fields	Customer profile display
`PATCH /v1/me/profile`	updated profile fields	Customer profile edits

Admin response surfaces:

Endpoint family	Response shape	Use for
`/v1/admin/members`	member summaries with user, membership type, status, source, roles, timestamps	Runtime member administration
`/v1/admin/invitations`	invitations with email, role, status, invite URL, expiry	Project invitation lifecycle
`/v1/admin/applications`	App Client and Management Client metadata	Client list, updates, and secret rotation
`/v1/admin/domains`	domain verification and binding records	Custom auth/API host lifecycle
`/v1/admin/webhooks/*`	endpoints, event catalog, deliveries, retry results	Webhook operations
`/v1/admin/billing/addons/sms/*`	SMS status, tiers, subscribe/cancel results	SMS add-on lifecycle

Public endpoint coverage

Surface	Endpoints
Auth	`/v1/auth/register`, `/v1/auth/login/password`, `/v1/auth/login/magic-link/request`, `/v1/auth/login/magic-link/verify`, `/v1/auth/login/phone/request`, `/v1/auth/login/phone/verify`, `/v1/auth/refresh`, `/v1/auth/logout`
OIDC	`/.well-known/openid-configuration`, `/connect/authorize`, `/connect/token`, `/.well-known/jwks.json`, `/connect/userinfo`
Session context	`/v1/sessions/switch-context`
Self-service	`/v1/me/context`, `/v1/me/memberships`, `/v1/me/authorization`, `/v1/me/security`, `/v1/me/linked-identities`, `/v1/me/profile`
Admin runtime	`/v1/admin/members`, `/v1/admin/invitations`, `/v1/admin/applications`, `/v1/admin/domains`, `/v1/admin/webhooks/*`, `/v1/admin/authorization/catalog`, `/v1/admin/roles`, `/v1/admin/permissions`
SMS add-on	`/v1/admin/billing/addons/sms/status`, `/v1/admin/billing/addons/sms/tiers`, `/v1/admin/billing/addons/sms/subscribe`, `/v1/admin/billing/addons/sms/cancel`

Done when

`GET /v1/me/context` returns the expected user, Workspace, Project, and environment.
`GET /v1/me/authorization` is used before showing privileged UI.
Management client tokens are created only on your server and used only for `/v1/admin/*`.
Profile PATCH sends at least one supported field and handles validation errors.
SMS, domains, and webhooks are wired only after the basic auth/session path works.

Troubleshooting

Symptom	Likely cause	Fix
`401`	Token missing, expired, revoked, or wrong host	Refresh once, then restart login or management token exchange
`403`	Token is valid but lacks Project permission	Read `/v1/me/authorization` and adjust Project roles
`400 customer_auth_context_binding_required`	`workspaceId` or `projectId` missing on context/token request	Use the top console selectors and pass both values
`409`	State conflict, duplicate identity, or stale edit	Reload current state before retrying
`402`	Plan or usage limit blocked the operation	Show upgrade/contact-admin path and avoid blind retries
`429`	Rate limited	Honor `Retry-After` and back off

API Overview: /docs/reference/api-overview
OpenAPI and Postman: /docs/reference/openapi-postman
Error Reference: /docs/reference/errors
Request Scoping: /docs/concepts/request-scoping
Webhooks Integration: /docs/quickstart/webhooks