Refresh Token Storage

When configuring your project settings, it's important to understand the differences in how refresh tokens can be stored with Descope, and what to do to ensure they are stored properly.

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.

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

Manage in Cookies (Recommended for Production)

Descope Client SDK automatically sets the refresh token as a cookie. For this option to work, you must also configure a CNAME record in your DNS and the custom domain setting in Descope console, which will securely restrict access to the stored refresh token.

Strict Cookies:

Descope utilizes strict cookies; this means that after successful authentication, Descope's response will set SameSite=Strict within the header of the cookie. The browser will only be able to send cookies to hosts with that custom domain (specified in the project settings) and subdomains of the set custom domain.

You should set the custom domain setting to something like app.example.com, and the CNAME record in your DNS for auth.app.example.com (subdomain of custom domain) should point to cname.descope.com (US) / CNAME.euc1.descope.com (EU). This implementation will set the refresh token as a cookie on auth.app.example.com.

Sample Custom Domain Setting

Sample CNAME Setting

Manage in Response Body

Descope Client SDK returns the refresh token in the body and stores it in browser local storage. This option does not require configuring a custom domain. You can chose to handle the refresh token as per your needs in your application client.