Sessions
A session is the authenticated period between when a user signs in and when that login ends. During a session, your app can recognize the user across page views, API calls, and actions without asking them to authenticate on every request.
Descope represents a session with two signed JWTs:
Note
If you use Descope as an OIDC provider, the session token is called an access token in OAuth terminology.
- Session token — short-lived; sent with API requests and validated by your backend (or API gateway).
- Refresh token — longer-lived; used by the Client or Mobile SDK to obtain a new session token when the current one expires.
Tokens are signed with a private key. Your server validates the session token using the public key or the Descope Backend SDK.
What is a Session?
A session groups a user's interactions with your application for a period of time. While the session is active, the client holds tokens that prove the user already authenticated. Your backend checks those tokens on protected routes instead of running the full login flow again.
On the web, the refresh token is often stored in an HttpOnly cookie so it survives page reloads and browser restarts until it expires. Mobile apps store both tokens in the device's secure storage (Keychain or EncryptedSharedPreferences). See Session management for platform-specific behavior.
A session ends when any of the following occurs:
- The user logs out — the refresh token is revoked on the server.
- The refresh token expires — configured in Project Settings → Session Management.
- Session inactivity timeout — no activity for the configured period; see session inactivity.
- The session is revoked server-side (for example, an admin disables the user or you call the logout API).
When a session ends, the user must authenticate again through your Flow or OIDC login.
How Sessions Work
- The user signs in through a Descope Flow or Client SDK auth functions (OTP, password, SSO, passkey, etc.).
- Descope returns a short-lived session token and a longer-lived refresh token.
- The Client or Mobile SDK stores both — HttpOnly cookie on web, Keychain / EncryptedSharedPreferences on mobile.
After authentication, the Client or Mobile SDK stores and manages both tokens. On each API call, the client sends the session token; your server validates it.
When the session token expires, the SDK silently exchanges the refresh token for a new one. If refresh fails, the user is redirected to sign in again.
Session timeouts, refresh rotation, and cookie delivery are configurable at the project or tenant level.
SSO and Multiple Sessions
When a user signs in with SSO, more than one session can exist at once:
| Session | Where it lives | Purpose |
|---|---|---|
| Application session | Your app (Client/Mobile SDK) | Tells your app and API that the user is signed in |
| Descope session | Descope | Tracks authentication for your project; used for refresh and logout |
| IdP session (SSO only) | The identity provider (Okta, Azure AD, etc.) | Lets the user sign in to Descope without re-entering credentials if the IdP session is still valid |
If the user already has an active IdP session, SSO can feel seamless — they may not see a login prompt. Your application session still depends on Descope issuing tokens to your client after the flow completes.
Common Use Cases
Protected areas of a public site — A storefront may allow anonymous browsing but require login for account settings or order history. Use the session token to gate those routes and API endpoints.
Always-authenticated apps — Dashboards and internal tools typically validate the session token on every API request. Pair short session token timeouts with refresh for security without frequent password prompts.
SPAs and mobile apps without a custom backend — The Client or Mobile SDK manages token storage and refresh. If you still call your own APIs, those APIs must validate the session token. For live authorization data that may change mid-session, use Token introspection.
Step-up and MFA — Sensitive actions can require a fresh authentication step. Descope issues a short-lived step-up token; see Step Up.
What's in the Token
Session and refresh tokens share the same claim payload.
For a full claim reference, such as mandatory vs optional claims, tenants, roles, custom claims, and more, see the Token Claims Management docs.
Note
Control what custom claims are included in your JWTs with JWT Templates and/or the Custom Claims flow action.
Generally, changes to custom claims (such as user attributes or roles) in the JWT are updated whenever a session token is refreshed.
When you need state that may have changed between refreshes — for example, an active tenant mid-session — use Token introspection or the Management SDK.
Related Documentation
- Token Claims Management — claim reference and configuration
- JWT Claims security best practices
- Refresh token rotation
- Backend SDK — authentication and session validation with Descope SDKs