Sessions

Sign a user in through ID, get a token, and use it to call the platform on their behalf.

A session is what you have after a user signs in: a token that proves who they are, which you attach to API calls so the platform acts as that user. Sign-in runs through ID, the platform's identity service. In this flow you never handle the password yourself — you hand the user to ID, ID signs them in, and your app gets back a token to use.

This page is for an app where a staff member or operator is driving: an internal tool, an admin console, a back-office integration. If the person signing in is a shopper on a storefront, you want storefront accounts instead — a different mechanism, described below. For server-to-server calls with no user present, use API keys.

How sign-in works

ID speaks OpenID Connect (OIDC), the standard sign-in protocol. The flow is a redirect round-trip:

text
1. Your app sends the user to ID's sign-in page.
2. The user signs in (password, social provider, or passkey) and approves.
3. ID redirects back to your app with a one-time code.
4. Your app exchanges that code for a token.
5. Your app sends the token as Authorization: Bearer <JWT> on API calls.

ID handles steps 2 and 3 — the screens, the password check, and the second factor if the user has one set up. Your app handles step 1 (send the user out), step 4 (exchange the code), and step 5 (use the token). Most OIDC client libraries do steps 1 and 4 for you once you give them ID's address and your app's client details.

To register your app and get its client ID and redirect URI, contact your platform administrator. The redirect URI is the address ID sends the user back to after sign-in.

Use the token

Once you have the token, send it on every API call as Authorization: Bearer <JWT>, along with your tenant slug. With the Web SDK, set it once on the client:

Web
import { Client } from "@revenexx/sdk";

const client = new Client()
  .setEndpoint("https://api.revenexx.com")
  .setTenant("<TENANT_SLUG>")
  .setBearerAuth("Bearer <JWT>");

Pass the value including the Bearer prefix. Every call made through this client now runs as the signed-in user, scoped to the tenant you set.

If you call the API directly over HTTP, send the same headers by hand:

cURL
curl https://api.revenexx.com/v1/orders \
  -H "Authorization: Bearer <JWT>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

Signing in a buyer is a different mechanism

The flow above is for a person who signs in through ID. A buyer — a shopper on a storefront — does not. The platform serves buyer accounts and sessions itself, through a separate set of routes under /v1/customers/auth, and a buyer session is not an ID token.

Storefront accounts documents that surface: register, login, me, logout and password recovery, with request bodies, and why those calls belong on a trusted server rather than in a browser. Sign a buyer in from your server walks through the whole session in order.

Don't mix the two. An ID token will not authenticate a buyer, and a buyer session will not authenticate a staff member.

When the token expires

Tokens are short-lived on purpose. When one expires, calls start failing with 401 Unauthorized. Your OIDC client library typically holds a refresh token from the original sign-in and can get a fresh token without sending the user back to the sign-in page. If refresh also fails, the session is over: send the user back through sign-in.

Treat a 401 as "get a new token", not as an error to show the user.

Sign out

To end the session, discard the token your app is holding (clear it from memory and any storage). For a full sign-out that also clears the user's session at ID — so the next sign-in asks for credentials again — send the user to ID's end-session endpoint. Most OIDC client libraries expose this as a logout() call.

Troubleshooting

  • 401 Unauthorized on every call — the token is missing, malformed, or expired. Confirm you send the Bearer prefix and that the token hasn't expired; refresh it if it has.
  • Redirect back to your app fails — the redirect URI your app sent must exactly match one registered for your client at ID, including the scheme and any trailing slash.
  • 403 with not a member of this tenant — the token is valid, but the user is not a member of the tenant in X-Revenexx-Tenant. The token identifies the user; the tenant header selects the tenant, and the two have to agree. A wrong slug is refused outright — it never returns another tenant's data.
  • 400 with missing X-Revenexx-Tenant — the tenant header is required on every call, including calls that carry a valid token.

What's next

Was this page helpful?