Storing Refresh Tokens

When you're using Descope on the client-side, it's imperative that you store your refresh tokens securely. Your refresh tokens are typically valid for 1 month, and if they are exposed, attackers can create their own session tokens to authenticate as someone else, effectively as if they had stolen their password.

Follow these guidelines to learn how to store your refresh tokens securely.

Set Refresh Token Expiry Time

The refresh token expiry time should be decided based on the requirements of your application (tradeoff between higher security and user experience). A shorter expiration time means that the user will need to authenticate frequently.

Handling Refresh Tokens in Cookies

If you are using our Client SDK (including Flows), Descope manages the refresh token storage for your application client. Depending on the project configuration, you can handle the refresh token in two different ways - manage in cookies and manage in response body.

It is recommended to store your refresh tokens in cookies, rather than in the browser localStorage. This is important because it will help mitigate the risk of XSS (Cross-site-scripting) attacks, since tokens in localStorage are accessible via JavaScript.

Since Descope uses httpOnly cookies, the refresh token will not be accessible using JavaScript. Descope cookies are also sameSite=strict and protected against cross-site request forgery attacks. You can configure this under Session Management Settings in the Descope Console.

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".