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. Copy the exact host and value 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:
4

Wait for verification

CDP polls DNS every few minutes and moves the domain to active once the records resolve. Because of DNS propagation, verification usually completes within minutes but can take a few hours. A domain that is not verified within 72 hours is marked failed; delete it, correct the DNS records, 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.

​
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.
The verification records were not found within 72 hours. Delete the failed domain, confirm the records are correct and published, then register it again. A failed domain must be removed before you can register a new one.
The domain was active but its verification record was later removed, so cookie issuance stopped and sessions revert to the default CDP domain. To resume first-party cookies, delete the deactivated entry and register the domain again. Like a failed domain, it must be removed before you can register a new one.

​
Replacing or removing a domain

To rotate to a new subdomain, register the replacement while the current domain is still active. The two coexist until the new one verifies, then it takes over. A failed or deactivated domain stays listed until you delete it and must be removed before you can register another. 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.