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:

Browser	Default for cross-site cookies
Safari	Blocked (even with SameSite=None; Secure), because "Prevent Cross-Site Tracking" is on by default
Firefox	Partitioned per top-level site (Total Cookie Protection)
Chrome / Edge	Allowed 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.

Recommended configuration

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, default SameSite=Lax is sufficient, 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

⚠️ Caveat: Safari's 7-day cookie cap

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 case	Impact
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.