Sessions

Introduction

Sessions is part of the Paycux platform. This page explains what it does, when to reach for it, and the smallest working setup you can ship.

Everything below applies to both environments. Build and test in staging, then promote the same configuration to production without changing your code — only the API key and client ID differ.

Integrating Sessions

Paycux issues a sealed session cookie alongside the access token. The cookie carries no user data of its own — it is an encrypted pointer that the SDK unseals on each request using your cookie password.

Access tokens are short-lived by design. Refresh them on the server, never in the browser, and treat a failed refresh as a signal to send the user back through sign-in.

Access Token

Access tokens are JWTs signed with a rotating key. Verify them against the JWKS endpoint for your client rather than a pinned public key, so rotation never causes an outage.

1https://api.paycux.com/sso/jwks/client_01M4KXD1PZXFWGWE9ZKPCQRAQ

Cache the key set and re-fetch on an unknown key ID. Reject any token whose issuer, audience or expiry does not match what you expect.

Refresh Token

Refresh tokens are long-lived, single-use and bound to the session they were issued for. Exchanging one returns a new access token and a new refresh token; the old refresh token is invalidated on use.

If a refresh token is replayed, Paycux treats it as a stolen credential and revokes the whole session family. Handle that response by sending the user back through sign-in rather than retrying.

Switching Organizations

An organization is the tenant boundary in Paycux. Connections, directories, roles and audit log streams all hang off an organization, and a user reaches your application through a membership in one.

Create an organization per customer, not per environment. The same organization exists in staging and production with separate configuration.

Signing Out

Paste the provider's metadata URL into the connection. Paycux reads the signing certificate and endpoints from it and re-reads them on a schedule, so a certificate rotation does not break the connection.

Configuring Sessions

Configuring Sessions is configured per environment in the dashboard, so staging and production can differ while your application code stays identical.

Changes take effect on the next request. There is no deploy step and no cache to clear.

Sign-out URIs

Sign-out URIs is handled by Sessions rather than by your application code. Paycux exposes it through the same API surface as the rest of the platform, so the client you already configured needs no additional setup.

Configuration lives in the dashboard and is versioned per environment. Change it in staging, confirm the behaviour, then apply the same change to production.