Authentication is the same for every program and every region. You log a user in, get a set of tokens, and send the ID token on every other call.
We recommend passkeys. They’re faster and safer than a password and a one-time code, and they’re our default sign-in method. See Passkey sign-in. Password sign-in (below) is fully supported as a fallback.

​
The one thing to know first

Logging in does not give you tokens straight away. Instead, login returns a challenge — a short message telling you what to do next, such as “enter your 2FA code” or “confirm your email.” You complete the challenge, and then you get your tokens. Notice that no entry point hands you tokens straight away — every path goes through a challenge, and brand-new users always pass through security setup first. The only way to get tokens is to finish whatever step the challenge points you to. The Log in page lists every challenge you might get and what to do for each.

​
Using your tokens

A successful login returns these tokens: Send the ID token in the header on every protected endpoint:
Use the id_token, not the access_token. The bearer token must be an ID token — we check the token’s token_use claim. An access_token in the Authorization header is rejected at the gateway with 403 before it reaches the endpoint.The access_token is still needed in two specific places, both as a request body field, never as the bearer: TOTP step-up confirmations (confirmation.accessToken) and Log out.
One thing, three names. Across these docs and the API, 2FA, MFA, and the SOFTWARE_TOKEN_MFA challenge all mean the same mechanism: a time-based one-time password (TOTP) from an authenticator app.

​
Telling us which program you are

Every auth call needs to know the program. Send it as a header:
You receive your program id from the Orenda team when your program is onboarded — if you don’t have one yet, contact the team. To use the test environment, also send:

​
What the responses look like

Auth replies come in three shapes, all starting with success:
Single sign-on (SSO) is also available. If you’d like your users to log in through your own identity provider (such as Google, Microsoft, or Okta) instead of email and password, we can set that up for you — see Single sign-on. Sign-in works differently there, so read that section instead of this one; everything after sign-in is the same.