Skip to main content
Cookie-based authentication configures Dynamic to set a secure, HttpOnly cookie containing a minified JWT instead of returning the token for in-app storage (e.g. localStorage). The browser sends the cookie automatically on same-origin requests, and your app code cannot read or modify it. This also enables cross-subdomain single sign-on: a user who signs in on one subdomain (e.g. app.example.io) is automatically authenticated on other subdomains (e.g. marketplace.example.io, shop.example.io) that share the same parent domain and Dynamic environment.

​
Why use it

  • Reduced XSS risk — the token is not accessible to JavaScript.
  • Session hijacking mitigation — HttpOnly cookies cannot be extracted by client-side scripts.
  • Cross-subdomain sessions — one sign-in covers all subdomains under the same parent domain.
See Security Best Practices and Tokens for more on token storage and security.

​
How it works

Dynamic requires a custom hostname — a subdomain you own, pointed by DNS CNAME to Dynamic’s API. This lets Dynamic’s backend set a first-party, secure HttpOnly cookie on your domain. For example, if your site is https://app.example.io, you could configure https://auth.example.io as the custom hostname. When a user signs in on app.example.io, Dynamic sets an HttpOnly cookie for .example.io. That cookie is then sent by the browser on any subdomain ending with .example.io.

​
Setup

Go to the Dynamic dashboard, expand Developer, and select Domains. Create a new cookie domain. Provide a subdomain you own. We recommend prefixing with auth — for example, auth.example.io for the domain example.io.

​
2. Configure DNS

Follow the instructions in the dashboard. You will need three DNS records:
  • 2 TXT records — for site and certificate verification.
  • 1 CNAME record — to proxy the custom subdomain to Dynamic.
Your CAA records must include either pki.goog or letsencrypt.org. If you use Vercel, see Vercel’s CAA records guide.
In sandbox, Dynamic also attempts to set the cookie from the SDK frontend to support local development and preview environments.

​
3. Update your SDK configuration

Once DNS is validated, configure your SDK to use the custom hostname as the API base URL. See the SDK-specific guide for your platform:

React

React Native

JavaScript

Go to Account Security in the dashboard and enable the cookie-based authentication toggle.
When enabled in live, Dynamic will no longer return a JWT to store in localStorage. The auth token will only be set as a cookie.
The cookie is stored as DYNAMIC_JWT_TOKEN in your browser’s cookies. It contains the minified Dynamic JWT. Before going live, verify your domain and cookie setup.

​
Domain configuration

The domain must be set in both your sandbox and live environments. The domain you configure must match the verified domain associated with your Dynamic environment — partial or mismatched domains cause cookie-setting to silently fail.
Cookies cannot be set on localhost. Once cookie authentication is enabled on your live environment, you cannot test against it from localhost unless you mask localhost to your live CNAME (e.g. via /etc/hosts or a local DNS override).

​
Testing locally

For local development, test against the sandbox environment. Dynamic includes the JWT in the response header (via localStorage) in sandbox so you can inspect tokens without a valid cookie domain.
The localStorage fallback for JWTs is only available in sandbox. It is not used in production.

​
Pre-launch checklist

1

Verify your domain

Confirm the domain is set in both your sandbox and live environments in the Dynamic dashboard.
2

Test on a staging domain

Run the full cookie authentication flow on a staging environment with a valid, resolvable domain — not localhost.
3

Confirm cookie is set

Check that the JWT is delivered as a cookie and is not falling back to localStorage.
4

Enable on live

Only enable cookie authentication on your live environment after staging validation passes.