SSO tokens

SSO uses the OAuth 2.0 authorization code flow. Your app sends the user to your program’s authorization URL, gets a short-lived code back on your redirect URI, and exchanges that code for tokens at your program’s token URL. Both URLs and your client id come from Orenda and are different for every program.

Only the authorization code flow is enabled. The implicit and password grants are not available on any program.

GET {AUTHORIZATION_URL}
  ?client_id={CLIENT_ID}
  &response_type=code
  &scope=openid+email+profile
  &redirect_uri={REDIRECT_URI}
  &state={random}
  &code_challenge={PKCE_CHALLENGE}
  &code_challenge_method=S256

Open it in a system browser or a secure webview — not an embedded view that your app can read, and not an iframe.

state — a random value you generate and check on the way back. It protects against cross-site request forgery. Always send it.
code_challenge — PKCE. Required for public clients (mobile, single-page apps), which are issued without a client secret. Generate a random code_verifier, send its SHA-256 hash base64url-encoded as the challenge, and keep the verifier for step 2.
redirect_uri — must match the one registered for your program exactly, including scheme, host, port, and path.

Skipping the provider chooser

By default the user sees a screen offering the available sign-in options. If your program has one identity provider and you want to go straight to it, add its name:

&identity_provider={IDENTITY_PROVIDER_NAME}

Orenda gives you this name with the rest of your program values.

2. Handle the redirect

The user signs in with your identity provider and lands back on your redirect URI:

{REDIRECT_URI}?code=8f3a…&state={the state you sent}

Check state matches before you do anything else. If it doesn’t, drop the response. On failure you get ?error=…&error_description=… instead — show the user a retry, and do not treat it as a server outage.

3. Exchange the code for tokens

POST {TOKEN_URL}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={CLIENT_ID}
&code={code}
&redirect_uri={REDIRECT_URI}
&code_verifier={PKCE_VERIFIER}

A confidential client sends its secret instead of code_verifier, as HTTP Basic auth (Authorization: Basic base64(client_id:client_secret)).

{
  "id_token": "eyJraWQ…",
  "access_token": "eyJraWQ…",
  "refresh_token": "eyJjdHki…",
  "expires_in": 300,
  "token_type": "Bearer"
}

The code is single-use and expires within minutes. Exchange it immediately on receipt. A replayed code fails, and a code left sitting in a URL bar or a log is a credential.

4. Call the API

Exactly as any other program — the ID token is the bearer token:

GET /v1/customers/{customerId}/accounts
Authorization: Bearer <id_token>
x-program-id: <your program id>

Use the id_token, not the access_token. The gateway checks the token’s token_use claim and rejects an access token with 403 before it reaches the endpoint. This catches people out on SSO because the token response lists access_token first.The access_token is only used as a request body field, for TOTP step-up confirmations and Log out.

Lifetimes and refreshing

Token	Lifetime	What it means for you
`id_token` / `access_token`	5 minutes (`expires_in` = `300`)	Refresh just before expiry, or reactively on a `401`. Refresh before a WebSocket reconnect too.
`refresh_token`	60 minutes	When it expires, refreshing fails and the user goes back through step 1.

To refresh, post to the same token URL:

POST {TOKEN_URL}
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={CLIENT_ID}
&refresh_token={refresh_token}

{
  "id_token": "eyJraWQ…",
  "access_token": "eyJraWQ…",
  "expires_in": 300,
  "token_type": "Bearer"
}

SSO sessions do not use POST /v1/auth/refresh. That endpoint is for sessions created by the Orenda sign-in endpoints. An SSO refresh token presented there will not work — refresh at your program’s token URL instead.

The refresh response does not include a new refresh_token. Keep the one you were issued at step 3 and reuse it until it expires. Storing the response wholesale and overwriting your saved refresh token with undefined is the single most common SSO bug — it logs the user out after five minutes.

A worked refresh

async function refreshTokens({ tokenUrl, clientId, refreshToken }) {
  const res = await fetch(tokenUrl, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      client_id: clientId,
      refresh_token: refreshToken,
    }),
  });

  if (!res.ok) {
    // Expired or revoked refresh token — send the user back to the authorization URL.
    throw new Error("SSO_SESSION_EXPIRED");
  }

  const t = await res.json();
  return {
    idToken: t.id_token,          // the bearer token
    accessToken: t.access_token,
    refreshToken,                 // unchanged — keep the original
    expiresAt: Date.now() + t.expires_in * 1000,
  };
}

Signing out

Send the user to your program’s logout URL to end the session at the identity layer, and clear the tokens you hold. Clearing tokens alone is not a sign-out: the next authorization request would sign the user straight back in from their provider session.

Common problems

Symptom	Cause
`redirect_mismatch` at step 1	The `redirect_uri` isn’t exactly the one registered for your program.
`invalid_grant` at step 3	The code was already used, expired, or the `code_verifier` doesn’t match the challenge.
`invalid_client`	Wrong client id for the environment — sandbox values used against production, or vice versa.
`403` from the Orenda API on every call	You sent the `access_token` as the bearer. Send the `id_token`.
`401` after five minutes	Working as designed — refresh.
Signed out after the first refresh	You overwrote the stored refresh token with the (absent) one from the refresh response.

Get started

Guides

Skipping the provider chooser

2. Handle the redirect

3. Exchange the code for tokens

4. Call the API

Lifetimes and refreshing

A worked refresh

Signing out

Common problems

​1. Send the user to sign in

​Skipping the provider chooser

​2. Handle the redirect

​3. Exchange the code for tokens

​4. Call the API

​Lifetimes and refreshing

​A worked refresh

​Signing out

​Common problems

1. Send the user to sign in

Skipping the provider chooser

2. Handle the redirect

3. Exchange the code for tokens

4. Call the API

Lifetimes and refreshing

A worked refresh

Signing out

Common problems