Exchange

curl --request POST \
  --url https://api.example.com/v1/auth/exchange \
  --header 'Content-Type: application/json' \
  --data '
{
  "subject_token": "<string>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "workspace_id": "<string>"
}
'

{
  "access_token": "<string>",
  "refresh_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "session_id": "",
  "id_token": "<string>",
  "scope": ""
}

auth

Exchange

AuthBridge: exchange an upstream Clerk token for a scoped CauseLoop JWT.

Verification is real, not stubbed:

When CLERK_JWKS_URL is configured we verify subject_token against the Clerk JWKS via security._decode_rs256 (which enforces CLERK_AUDIENCE and authorized-parties/azp). A failed verification is a 401.
The verified Clerk sub and email claim resolve the CauseLoop user via external_id first, then email. Outside production we may JIT-fall back to the first seeded user; in production an unknown identity is a 403.
The workspace + role come from the requested (and member-checked) workspace or the user’s first active membership; we then mint a scoped token via sign_access_token (scopes derive from PERMISSIONS).

Dev fallback: when CLERK_JWKS_URL is NOT set and ENVIRONMENT != “production” we preserve the legacy seed-user behavior so local/mock dev keeps working. When CLERK_JWKS_URL is NOT set and ENVIRONMENT == “production” we refuse (503). (identity-architecture.md §3.1 token-exchange grant)

POST

auth

exchange

Exchange

curl --request POST \
  --url https://api.example.com/v1/auth/exchange \
  --header 'Content-Type: application/json' \
  --data '
{
  "subject_token": "<string>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "workspace_id": "<string>"
}
'

{
  "access_token": "<string>",
  "refresh_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "session_id": "",
  "id_token": "<string>",
  "scope": ""
}

Body

application/json

AuthBridge: exchange an upstream JWT (Clerk/SAML/OIDC) for a Causeloop JWT.

subject_token

string

required

subject_token_type

string

default:urn:ietf:params:oauth:token-type:jwt

workspace_id

string | null

Response

Successful Response

access_token

string

required

refresh_token

string

required

token_type

string

default:Bearer

expires_in

integer

default:3600

session_id

string

default:""

id_token

string | null

scope

string

default:""

Me Get Session

⌘I