Skip to main content

I cannot connect to the Kuroco API from my iPhone or Safari browser. What should I do?

Symptom​

In Safari (macOS / iOS / iPadOS), cookie-based authentication may fail intermittently — API requests return 401/403 right after a successful login, users get logged out repeatedly, and the same flow works fine in Chrome. This happens because the Kuroco API's auth cookie is being treated as a third-party cookie.

Why this happens​

A cookie is first-party only when its host shares the same registrable domain (eTLD+1) as the page. Browsers apply different defaults to cross-site cookies:

BrowserDefault for cross-site cookies
SafariBlocked (even with SameSite=None; Secure), because "Prevent Cross-Site Tracking" is on by default
FirefoxPartitioned per top-level site (Total Cookie Protection)
Chrome / EdgeAllowed with SameSite=None; Secure

In Kuroco's default setup the two registrable domains differ — www.example.com (eTLD+1: example.com) vs example.a.kuroco.app (eTLD+1: kuroco.app) — so Safari drops the auth cookie.

Use a custom API domain so the front-end and API share the same registrable domain. Either of these works:

  • https://www.example.com + https://api.example.com
  • https://example.com + https://api.example.com

The cookie becomes first-party, and Safari / Firefox restrictions no longer apply.

Setup:

  1. Register api.example.com in Custom domain / TLS certificate and point it at your Kuroco environment
  2. Update the API base URL in Account settings

Even with a matching parent domain, Safari may cap the cookie's Max-Age / Expires at 7 days. The Kuroco custom API domain is a CNAME pointing to <sitekey>.g.kuroco.app, and WebKit's CNAME-cloaking mitigation (Safari 14, extended in Safari 16.4 to also cover A/AAAA records whose IP ranges differ significantly from the page's server) caps cookies on such hosts at 7 days. Switching from CNAME to an A record does not help — Kuroco's API IPs are not in your front-end's range, so Safari 16.4+ applies the same cap.

The cookie is not blocked — active sessions work normally. But users who do not return within 7 days will be asked to log in again.

Use caseImpact
Daily-use internal tool / dashboard✅ No practical issue
Marketing site / short-session campaign✅ No practical issue
Public site with infrequent logins⚠️ Safari users may be logged out unexpectedly
Long-lived "remember me" on Safari❌ Not possible with cookies — use token auth

Workaround: token-based authentication​

Use token-based authentication instead. The access token is sent in the X-RCMS-API-ACCESS-TOKEN request header rather than as a cookie, so ITP's cookie restrictions do not apply. Refresh tokens can renew the access token without forcing the user to re-login.

Examples​

❌ Failed (cross-site cookie blocked by Safari)​

  • Front-end: https://www.example.com
  • API: https://example.a.kuroco.app

✅ Recommended​

  • Front-end: https://www.example.com (or https://example.com)
  • API: https://api.example.com

*Note: If you do not use cookie-based authentication, no domain change is needed. Token auth is unaffected.

Development tip​

This issue does not appear in Chrome by default, so Chrome is convenient during development. Before production, verify on Safari (macOS and iOS): login flow, sustained session behavior, and — if long-lived sessions matter — behavior after 7+ days of inactivity.

info

See Tutorial: Using your own API domain with KurocoFront for the full setup procedure.

Support

If you have any other questions, please contact us or check out Our Slack Community.

Contact form
Join Kuroco Slack community