Lamba

Choose this when

Use hosted auth when you want Lamba to own login, registration, and provider entry screens while your product owns the application experience after sign-in.

Hosted auth is the best starting point when:

you need browser redirect login
you want OAuth/OIDC compatibility
you do not want to build password, registration, and provider UI first
you need branded auth domains later

Before you start

You need a Workspace, Project, environment, and App Client. Configure sandbox and production separately. A redirect URI that works in sandbox is not automatically valid in production.

Get credentials from Console

Create or open the customer application from Integration > App Clients in the selected Project.

Credentials and configuration values
Value	Console source	Env var	Used for
Client ID	Integration > App Clients > Client ID	`LAMBA_CLIENT_ID`	The `client_id` in `/connect/authorize` and `/connect/token`
Client secretSecret	Integration > App Clients > Create or Rotate secret	`LAMBA_CLIENT_SECRET`	Only confidential server-side token exchange
Redirect URI	Integration > App Clients > Edit > Redirect URIs	`LAMBA_REDIRECT_URI`	Exact callback URL that receives the authorization code
Post-logout redirect URI	Integration > App Clients > Edit > Post-logout redirect URIs	`LAMBA_POST_LOGOUT_REDIRECT_URI`	Optional destination after hosted logout
Workspace and Project IDs	Top Workspace / Project selector	`LAMBA_WORKSPACE_ID and LAMBA_PROJECT_ID`	Switching the signed-in user into runtime Project context

Configure environment variables

LAMBA_AUTH_BASE_URL=https://test.id.uselamba.com
LAMBA_API_BASE_URL=https://test.api.uselamba.com
LAMBA_CLIENT_ID=<app-client-id>
LAMBA_CLIENT_SECRET=<confidential-client-secret-if-used>
LAMBA_REDIRECT_URI=http://localhost:3000/auth/callback
LAMBA_WORKSPACE_ID=<workspace-id>
LAMBA_PROJECT_ID=<project-id>
LAMBA_ENV=test

Make the first request

Redirect the user to the authorize endpoint. Generate state, nonce, code_verifier, and code_challenge for each login attempt.

GEThttps://test.id.uselamba.com/connect/authorize

Auth: No bearer token; the browser starts the login request
Used for: Shows hosted login and returns an authorization code to your redirect URI

GET https://test.id.uselamba.com/connect/authorize
  ?response_type=code
  &client_id=<app-client-id>
  &redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth%2Fcallback
  &scope=openid%20profile%20email
  &code_challenge=<base64url-sha256>
  &code_challenge_method=S256
  &state=<opaque-state>
  &nonce=<opaque-nonce>

Exchange the returned code on your callback route.

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

Auth: PKCE for public clients; client secret or Basic auth for confidential clients
Used for: Exchanges an authorization code for tokens

await fetch(`${process.env.LAMBA_AUTH_BASE_URL}/connect/token`, {
  method: "POST",
  headers: { "content-type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    client_id: process.env.LAMBA_CLIENT_ID!,
    code,
    redirect_uri: process.env.LAMBA_REDIRECT_URI!,
    code_verifier,
  }),
});

After login, enter Project runtime context before calling api.*.

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

Request fields

Authorize request fields:

Request and response fields
Field	Type	Required	Meaning	Notes
`response_type`	string	Required	OAuth response type.	Use `code`.
`client_id`	string	Required	The App Client ID from `Integration > App Clients`.	-
`redirect_uri`	URI	Required	Callback URL registered on the App Client.	Must match exactly.
`scope`	space-separated string	Required	OIDC scopes requested by the app.	Start with `openid profile email`.
`state`	string	Required	Opaque value used to bind the callback to the browser session.	-
`nonce`	string	Required	Opaque value used to validate the ID token.	-
`code_challenge`	string	Required	Base64url SHA-256 challenge derived from the code verifier.	-

Token request fields:

Request and response fields
Field	Type	Required	Meaning	Notes
`grant_type`	string	Required	OAuth grant being exchanged.	Use `authorization_code` for hosted auth callbacks.
`code`	string	Required	Authorization code received on your redirect URI.	-
`code_verifier`	string	Required	Original verifier used to create the PKCE challenge.	-
`client_secret`	string	Conditional	Secret for confidential clients.	Keep server-side only. Public clients omit this field.

Response fields

Token exchange returns OAuth/OIDC token fields. When your app needs Lamba Customer API calls, use the returned access token to call POST /v1/sessions/switch-context, then use the scoped customer session token returned by that operation for api.*.

Request and response fields
Field	Type	Required	Meaning	Notes
`access_token`	string	Required	Bearer token returned by the auth host.	Exchange into Project context before using Customer API routes.
`id_token`	JWT	Conditional	OIDC identity token when OIDC scopes are requested.	Validate issuer, audience, nonce, expiry, and signature.
`refresh_token`	string	Conditional	Credential used to rotate the session when issued.	Store server-side or in platform-secure storage.
`expires_in`	number	Required	Access token lifetime in seconds.	-
`token_type`	string	Required	Bearer token type.	-

Done when

The authorize request starts from the selected sandbox or production issuer.
The redirect URI exactly matches the App Client configuration.
Your callback validates state and exchanges the code with PKCE.
Token validation uses discovery and JWKS from the same issuer.
Switch-context returns a scoped customer session before Customer API calls.

Troubleshooting

Symptom	Likely cause	Fix
`redirect_uri_mismatch`	Callback URL differs from the App Client value	Copy the exact URI into `Integration > App Clients > Edit`
`invalid_client`	Wrong client ID, secret, Project, or environment	Confirm top Project selector and environment badge, then rotate the secret if needed
`invalid_grant`	Code expired, verifier mismatch, or code reused	Restart login and keep one verifier per attempt
ID token validation fails	Issuer or JWKS host mismatch	Use `/.well-known/openid-configuration` from the same auth host
Customer API returns `401`	Raw hosted auth token was used where a scoped session is required	Call `POST /v1/sessions/switch-context` first

OIDC Integration: /docs/quickstart/oidc
Next.js Customer Auth Integration: /docs/quickstart/nextjs
Auth and Session Contracts: /docs/reference/auth-session-contracts
Custom Domains Integration: /docs/quickstart/custom-domains