Authentication is the same for every program and every region. You log a user in, get a set of tokens, and send the access 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:
TokenWhat it’s for
access_tokenSend this on every other call (see below). Short-lived — it expires after expires_in seconds (about 5 minutes).
id_tokenA JWT with the user’s details. Also used to connect WebSockets. Same ~5 minute life as the access token.
refresh_tokenUse it to get fresh tokens when the access token runs out — see Sessions. Lasts about 1 hour; after that the user signs in again.
Send the access token in the header on every protected endpoint: 
Authorization: Bearer <access_token>
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: 
x-program-id: <your program id>
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: 
x-sandbox: true

​
What the responses look like

Auth replies come in three shapes, all starting with success: 
// 1. Tokens or a challenge
{ "success": true, "data": { /* tokens, or the next challenge */ } }

// 2. A simple message (for example, after register)
{ "success": true, "message": "Confirmation code sent to email" }

// 3. An error
{ "success": false, "code": "INVALID_CREDENTIALS", "message": "Invalid email or password" }
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. Contact the team — you’ll get a separate SSO guide, as the steps are different from the ones here.