Storing Session Tokens

Session tokens (in the form of JWTs) are used to authenticate requests from a client to your backend. If compromised, attackers can impersonate users and gain unauthorized access to protected resources.

Set Session Token Expiry Time

The Session Token Timeout setting, under your Session Management settings defines the expiry length of the session token, before it must be refreshed using a valid refresh token.

Configuring a shorter lifespan minimizes the risk window if a session token is intercepted or leaked. The expiry time should be configured to strike the right balance between minimizing security risks and maintaining a seamless user experience.

Session Token Management

Depending on the project configuration, you can handle the session token in two different ways - in cookies or in response body.

Managing with Cookies

• When managing session tokens in cookies, Descope handles storage automatically by setting secure httpOnly cookies tied to your custom domain.
• This approach is generally recommended for production environments because it significantly reduces the risk of token theft through Cross-site Scripting (XSS) attacks, because JavaScript running in the browser cannot access httpOnly cookies.
• Session token cookies set by Descope are by default marked as sameSite=strict and secure, which adds protection against Cross-site Request Forgery (CSRF) and ensures they are only transmitted over HTTPS.

As a best practice, make sure to limit your custom domain scope as much as possible. This more specific scope will limit the number of places your browser will send the cookie. If your cookie only needs to be sent with requests using the domain "app.company.com", then your scope should be that rather than the entire website "company.com".

Managing with Response Body

• With this approach, the session token is returned in the API response and must be stored and managed by your application code (e.g. in JS memory or in localStorage).
• This approach is easier to implement during development and local testing, and gives you full control over token lifecycle, including manual expiration and renewal.
• However, storing tokens in localStorage or memory makes them vulnerable to Cross-site Scripting (XSS) attacks, since malicious scripts can potentially access them.