OIDC Quickstart

Overview

Use this guide to integrate Lamba as your OpenID Connect provider.

• Auth host: https://id.uselamba.com
• Customer API host: https://api.uselamba.com
• Discovery and token exchange happen on the auth host.
• Runtime profile and authorization reads happen on the customer API host.

1) Discovery endpoint

Use the issuer discovery document as your source of truth:

curl -s https://id.uselamba.com/.well-known/openid-configuration

Persist these values:

• issuer
• authorization_endpoint
• token_endpoint
• userinfo_endpoint
• jwks_uri

If you use a branded auth domain such as https://auth.customer.com, discovery and issuer move to that branded host.

2) Authorization Code + PKCE

• Use response_type=code.
• Public clients must send code_challenge and code_challenge_method=S256.
• Always use a unique state and nonce per login attempt.

3) Redirect URI exact match

redirect_uri must match a registered URI exactly. No wildcard redirects.

4) Token exchange

await fetch('https://id.uselamba.com/connect/token', {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: 'client_web_prod',
    code,
    redirect_uri: 'https://app.example.com/callback',
    code_verifier,
  }),
});

5) Token validation checklist

Validate:

• iss equals the discovery issuer exactly
• aud contains your client ID
• exp and nbf are valid with bounded clock skew
• nonce matches the original browser auth request

For branded auth domains, the expected iss is the branded host returned by discovery, not id.uselamba.com.

6) JWKS caching strategy

• Cache keys by kid.
• On unknown kid, refresh JWKS and retry validation once.
• Use bounded TTL and fail closed if signature validation still fails.

7) Exchange into a customer session before calling the customer API

OIDC signs users in on the auth host. The current customer API contract expects the customer session token returned by the auth host, not the raw OIDC access token.

If your app needs api.*, exchange first:

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

Then call the customer API with the returned customer session token:

curl https://api.uselamba.com/v1/me/context \
  -H "Authorization: Bearer $CUSTOMER_SESSION_TOKEN"

8) Failure handling map

9) Refresh + session behavior

• Treat refresh tokens as sensitive credentials.
• Revoke or rotate on membership and security changes.
• Clear local session state at logout.

Security reminders

• Use Authorization Code flow only.
• Do not use Implicit flow.
• Keep sandbox and production issuers and clients separate.