Skip to main content
The Portal Web SDK requires a custom subdomain to work reliably in Safari and other browsers that block third-party cookies. This guide explains why, and walks you through the setup.

​
Why you need this

When you initialize Portal, the SDK creates a hidden iframe served from Portal’s servers (web.portalhq.io by default). Everything sensitive is scoped to that iframe’s origin: the Client Session Token cookie that authenticates your user, and the user’s MPC signing share in LocalStorage. Your application’s JavaScript cannot read either, which protects the signing share from XSS bugs in your app. Browsers treat cookies and storage that belong to a different site than the one in the address bar as third-party. Safari blocks third-party cookies by default, Firefox partitions them, and Chrome blocks them in Incognito. When they are blocked, the iframe cannot keep its session or its signing share, and wallet operations fail. A custom subdomain fixes this: point portal.yourdomain.com at Portal, and the SDK loads the iframe from that subdomain. Same Portal servers, but now first-party in every browser. The iframe is still a different origin than your app, so the signing share stays isolated.

​
Setup instructions

You configure your custom subdomain in the Portal Dashboard. The Dashboard shows the DNS record to create, checks it, and provisions the TLS certificate for your subdomain.

​
1. Add the domain in the Portal Dashboard

  1. In the Portal Dashboard, select the environment your Web SDK uses. Web SDK domains are managed per environment.
  2. Under Configuration, open Web SDK Domains.
  3. Click Add domain, enter your subdomain (for example portal.yourdomain.com), and click Add domain to confirm.
Managing Web SDK domains requires additional verification. If prompted, enter the 6-digit code from your authenticator app. If you have not set up an authenticator app yet, the Dashboard walks you through enrollment first.
Your subdomain must be a child of the domain your application runs on. If your application is at yourdomain.com, configure portal.yourdomain.com. If your application is at app.yourdomain.com, configure portal.app.yourdomain.com. The browser only treats the iframe as first-party when the subdomain and your application share a site.

​
2. Create the DNS record

The new domain appears in the list with a Pending status, along with the DNS record to create. Create a CNAME record in your DNS provider:
  1. Set the DNS Record Type to CNAME.
  2. Set the Name or Host field to your subdomain (for example portal, which creates portal.yourdomain.com).
  3. Set the Data or Content field to web.portalhq.io.
To confirm the record resolves, run:
The answer section should show your subdomain pointing to web.portalhq.io:
If the CNAME does not appear, wait for DNS propagation (typically minutes, up to a few hours depending on your provider) and check that the record was created on the correct zone.

​
3. Wait for the domain to become active

Once your CNAME resolves, Portal verifies the record and issues a TLS certificate for your subdomain. The domain’s status in Web SDK Domains changes from Pending to Active when it is ready. Click Refresh to check the latest status.
Verifying DNS and provisioning the certificate can currently take up to 1-2 hours. Until the domain is Active, requests to your subdomain fail with a TLS error. This is expected.
If the domain shows an Invalid status, the Dashboard displays the DNS validation error. Fix the DNS record, then click Retry activation.

​
4. Set the host in your SDK config

Pass your subdomain as the host when you initialize Portal. Without this step, the SDK keeps using web.portalhq.io and nothing changes.

​
5. Verify end to end

Open your application in Safari (it blocks third-party cookies by default, so it is the strictest test) and run a wallet operation like generate or sign. If it succeeds in Safari, the subdomain is configured correctly.

​
Security in depth

Running the Web SDK on a separate subdomain keeps Portal’s resources isolated from your main application. Cookies The Web SDK uses a cookie to store the ClientSessionToken, which authenticates a user to the Portal backend. The cookie is configured with the http-only and secure flags, so it is only transmitted over TLS and is inaccessible to JavaScript. The cookie is scoped to the subdomain, which means it is not included on requests to your application, only on requests to Portal’s backend. LocalStorage The Web SDK uses LocalStorage to store the user’s signing share, which is used during MPC operations to sign messages and transactions. Values in LocalStorage are scoped to the subdomain, so they cannot be accessed by your application’s JavaScript. This isolation protects the MPC share from XSS bugs or malicious scripts on your web application.

​
Troubleshooting

  • Works in Chrome but not Safari: the host option is probably not set, so the SDK still loads the iframe from web.portalhq.io. Check step 4.
  • TLS or certificate error on the subdomain: the certificate has not been issued yet, or the CNAME changed after issuance. Check that the domain shows Active in Web SDK Domains in the Portal Dashboard, and verify the record with dig.
  • Domain shows Invalid in the Dashboard: Portal could not validate the DNS record. Review the error shown on the domain, fix the CNAME, then click Retry activation.
  • dig shows no CNAME: the record has not propagated, or it was created on a different zone than your application’s domain.