Before you start
Lamba keeps the global UserSession separate from runtime Project scopes. applicationId is audit-only inside scope records. Runtime revoke granularity is Project, not application.
What you build
A session starts as a global identity session and may enter Project runtime context. The scoped token is what your product should use for customer API calls.
Implementation steps
1) Authenticate the user
Use hosted auth, OIDC, social login, or direct auth APIs to establish the global Lamba User session.
2) Switch into Project context
When your product needs runtime access, call context switch with the 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"
}'
3) Use scoped access for runtime calls
Use the returned scoped token for api.* routes. Do not send internal console headers to public customer APIs.
4) Treat revoked scopes as terminal
Revoked runtime scopes must not auto-heal from the current global session. A revoked runtime scope may return only after explicit re-entry triggers a new scoped-auth event.
Security and operational notes
- Keep refresh and revoke behavior observable.
- Re-read authorization after role assignment or revoke flows.
- Revoke by Project scope, not by application ID.
- Log session ID, scope ID, Project, environment, and trace/correlation ID for sensitive flows.
Troubleshooting
If a user remains signed in globally but cannot call runtime APIs, inspect the Project scope. If the scope was revoked, start an explicit re-entry flow instead of silently restoring access.
Related docs
- Auth and Session Contracts:
/docs/reference/auth-session-contracts - Request Scoping:
/docs/concepts/request-scoping - Customer API request and response contract:
/docs/quickstart/customer-api