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. 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 real person is driving: a storefront, a customer portal, an internal tool. For server-to-server calls with no user present, use API keys instead.

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/customers/me \
  -H "Authorization: Bearer <JWT>" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

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.
  • Calls succeed but return another tenant's data, or none — check X-Revenexx-Tenant is the correct slug. The token identifies the user; the tenant header selects the tenant.

What's next

Was this page helpful?