Skip to main content
First-party cookie support is in limited access. Request access to have it enabled for your project before you start.

​
Overview

Non-custodial user wallet sessions use a refresh token to keep users signed in. CDP stores that token in one of two ways: an HttpOnly cookie, which page scripts cannot read, or browser localStorage as a fallback. By default CDP uses the HttpOnly cookie, scoped to CDP’s domain (api.cdp.coinbase.com). When your app runs on its own domain, that cookie is third-party, and browsers that block third-party cookies (Safari, Firefox, Brave, Chrome in Incognito) fall back to storing the refresh token in localStorage. First-party cookie support lets you serve that cookie from a subdomain of your own site (for example auth.myapp.com), so the refresh token stays in an HttpOnly cookie on every major browser.
The cookie is issued with SameSite=Lax, HttpOnly, and Secure. These attributes are fixed and are not configurable.

​
How it works

You add DNS records at your provider that route a subdomain you own to CDP and prove you control it. CDP issues and renews the TLS certificate for the subdomain and serves authentication requests on it, so the session cookie is issued as first-party. Once the domain is active, the SDK detects it automatically from your project configuration and sends authentication requests to https://<your-subdomain>/.... You do not change any application code.

​
Requirements

  • The cookie domain must be a subdomain (for example auth.myapp.com). Apex domains such as myapp.com are not supported.
  • A project can have one active cookie domain at a time.
  • You need access to your DNS provider to add the records CDP returns.

​
Setup

1

Request access

First-party cookie support is in limited access. Request access to have it enabled. Once access is confirmed, the first-party cookie settings appear in your project’s wallet security configuration in CDP Portal.
2

Register your subdomain

In CDP Portal, open your project’s wallet security settings and add your cookie domain (for example auth.myapp.com). Portal returns the DNS records you need to publish.
3

Add the DNS records

Add the returned records at your DNS provider. Use the names and values from Portal, not the examples below. The verification token, certificate delegation target, and routing host are specific to your project.The records below are illustrative examples only:
Some DNS providers add your domain to the Name or Host field automatically. If yours does, enter only auth, _cdp-verification.auth, and _acme-challenge.auth for the three records. Check that the full names match Portal—for example, auth.myapp.com, not auth.myapp.com.myapp.com.
Keep the _acme-challenge record publicly visible as a CNAME. Disable proxying or CNAME flattening for this record if your DNS provider supports those features. This applies to the validation record, not your main auth CNAME or entire domain.
4

Wait for verification

CDP checks the ownership TXT record every few minutes and marks the domain active when it matches. DNS propagation usually completes within minutes but can take a few hours. If verification does not complete within 48 hours, the domain is marked failed. Correct the DNS records, delete the failed entry, and register the domain again.

​
DNS and verification

The three records serve distinct roles:
  • Ownership: the _cdp-verification.<subdomain> TXT record carries a token that proves you control the subdomain. CDP checks for it before issuing cookies on your domain.
  • TLS: the _acme-challenge.<subdomain> CNAME delegates certificate validation to CDP, so the certificate for your subdomain is issued and renewed automatically without you republishing a challenge.
  • Routing: the CNAME on the subdomain itself points traffic at CDP’s proxy, which terminates TLS and sets the first-party cookie.
Keep all three records in place while first-party cookies are enabled. CDP needs them for ongoing ownership verification, routing, and certificate renewal.

​
Status lifecycle

The domain is registered and awaiting DNS verification. Make sure all records from Portal are published exactly as shown. CDP rechecks every few minutes.
DNS is verified and first-party cookies are being issued on your subdomain. CDP rechecks active domains periodically to confirm the records are still in place.
Ownership verification did not complete within 48 hours. Correct the DNS records, delete the failed entry, and register the domain again. Use the records returned by the new registration. A failed domain must be removed before you can register a new one.
The domain was active, but its ownership TXT record is now missing or no longer matches. Restore the original TXT record from Portal. CDP continues checking and automatically reactivates the domain when ownership verification succeeds. You do not need to delete and register the same domain again.

​
Replacing or removing a domain

To switch to a new subdomain, register it while the current domain is still active. The new domain replaces the current one once ownership is verified. Remove any failed or deactivated entry before registering a different domain. To reactivate the same deactivated domain, restore its original ownership TXT record instead. Removing the active domain reverts sessions to the default CDP domain immediately. The DNS records you added become inert and can be safely deleted from your provider.