SSO tokens

SSO is 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 aren’t 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 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 get no client secret. Generate a random code_verifier, send its SHA-256 hash base64url-encoded as the challenge, and keep the verifier for step 3.
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 listing the available sign-in options. If your program has one identity provider and you want to skip that screen, 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. It isn’t 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 the moment you receive it. A replayed code fails, and a code sitting in a URL bar or a log is a credential.

4. Call the API

Same as any other program. The access token is the bearer token:

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

Lifetimes and refreshing

Token	Lifetime	What it means for you
`access_token` / `id_token`	5 minutes (`expires_in` = `300`)	Refresh just before expiry, or on a `401`. Refresh the `access_token` 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 don’t use Refresh tokens. That endpoint is for sessions created by the Orenda sign-in endpoints. An SSO refresh token sent there fails. Refresh at your program’s token URL instead.

The refresh response doesn’t include a new refresh_token. Keep the one from step 3 and reuse it until it expires. Storing the response wholesale and overwriting your saved refresh token with undefined is the most common SSO bug. It logs the user out after five minutes.

Refresh example

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,
    // with identity_provider set so they skip the account chooser (see step 1).
    throw new Error("SSO_SESSION_EXPIRED");
  }

  const t = await res.json();
  return {
    accessToken: t.access_token,  // the bearer token, including for WebSockets
    idToken: t.id_token,          // identity claims only, not a bearer token
    refreshToken,                 // unchanged, keep the original
    expiresAt: Date.now() + t.expires_in * 1000,
  };
}

Signing out

Clear the tokens you hold, then send the user to your program’s logout URL to end the session at the identity layer. Clearing tokens alone isn’t a sign-out: the next authorization request signs the user straight back in from their provider session.

GET {LOGOUT_URL}
  ?client_id={CLIENT_ID}
  &logout_uri={LOGOUT_REDIRECT_URI}

logout_uri is where the user lands afterwards. It has to be one of the sign-out URLs registered for your program, the same way redirect_uri has to be registered for sign-in.

Use logout_uri, not redirect_uri. If you send redirect_uri (with response_type=code) to the logout URL, the session is ended and the user is then shown a hosted login page instead of being sent back to your app.

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 against production, or the other way round.
`401` after five minutes	Working as designed. Refresh.
A hosted login page appears after sign-out	You sent `redirect_uri` to the logout URL. Send `logout_uri` instead.
An account-chooser page appears when re-authenticating	The authorization URL was built without `identity_provider`. See Skipping the provider chooser.
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

Refresh example

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

​Refresh example

​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

Refresh example

Signing out

Common problems