Authentication: OIDC

Casap acts as the relying party and federates with your OpenID provider using the authorization code flow. Use this if you have an OIDC provider and would rather not run SAML.

OIDC authorization code sequence. You send the member to Casap's login endpoint with your organization id. Casap redirects to your provider's authorization endpoint. Your provider authenticates the member and returns an authorization code to Casap's callback. Casap validates the response, creates a member session, and redirects to your registered URL with a one-time code.

Endpoints

Start a login — GET https://api-sandbox.casaphq.com/v1/sso/oidc/login?org_uuid=<org-uuid>
Callback, which you register with your IdP — GET https://api-sandbox.casaphq.com/v1/sso/oidc/callback

The callback carries no org_uuid. Register the bare callback URL as your redirect URI.

The flow

Point the member's browser at the login URL with your org_uuid.
Casap redirects to your authorization endpoint.
Your provider authenticates the member and redirects back to our callback with a code and the state.
Casap validates the response and the id_token.
Casap creates a session and redirects to your registered URL with a one-time ?code= (or ?token=).

The login request is time-limited. Start it fresh rather than replaying an old link.

Configuring your provider

Three options, in order of preference:

Discovery (default) — give us an issuer URL and we read <issuer>/.well-known/openid-configuration.
Static endpoints — give us the authorization, token and JWKS URLs yourself.
Inline key — give us the authorization and token URLs plus the key set directly.

You also give Casap a client id and client secret, which we store encrypted. The openid scope is always requested; tell us any others you need.

Claims we read from the id_token

email (required) — falls back to preferred_username if absent. A login carrying neither is rejected.
given_name, family_name (optional) — combined into the member's name.
name (optional) — used when given_name and family_name are not both present.
customerLookup (optional) — describes how to find the member. An invalid value is ignored rather than failing the login.

The audience must be your client id.

Unlike SAML, we do not read a tax id or party id straight from the token. The member identifier arrives in customerLookup, or we derive it from your platform during login.

Errors

What happened	Status
`org_uuid` missing on login	400
We could not resolve your provider config	404
The login request was invalid or expired	400
Your IdP returned an error, or code exchange failed	401
The `id_token` failed verification	401
No usable email claim	400

Authentication: SAML 2.0

Knowing when the member is done