Testing Locally with Tokens Stored in Cookies

When using Descope with your application and testing in your local environment, you may encounter a 401 Unauthorized error when trying to authenticate if you're storing your refresh tokens in cookies (the recommended way of handling these tokens). This happens because the cookies are tied to your configured custom domain and are not sent in requests made from a different origin like localhost.

If you need to test locally, assuming you're using localhost, the custom domain that you configure in the Descope Console will not allow you to authenticate if the Cookie Policy is configured as Strict or Lax.

This guide will instruct you how to test cookies within a local environment.

Configure Descope Project

You may configure refresh and session tokens to be stored in cookies:

• Only the refresh token may be stored as a cookie, or
• Both refresh and session tokens may be stored as cookies

When testing locally, to ensure proper functionality on localhost, you must adjust the Cookie Policy settings accordingly in your Descope Project Settings.

Case 1: Storing Refresh Token as Cookie

• In the Descope Project Settings, go to the Session Management section.
• For the Refresh Token, select "Manage in cookies"
• Set the Cookie Policy to None This ensures the refresh token can be read during cross-origin requests on localhost.

Case 2: Storing both Refresh & Session Tokens as Cookies

• In the Descope Project Settings, go to the Session Management section.
• For both Refresh Token and Session Token options, select "Manage in cookies"
• Set both Cookie Policies to None

Make sure to Save the above changes.

The None policy explicitly allows cookies to be sent in cross-origin requests, which is necessary when running your application on localhost while the cookies are tied to your custom domain.

Test Cookies in Local environment

After configuring your token management and cookie policies, you can now utilize your custom baseUrl within your locally running application to test authentication flows.

Here is an example of testing cookie storage with localhost.