Cookies

Cookies are HttpOnly — do not attempt to read or write kai_auth from JavaScript. Doing so will not work and is the wrong abstraction. Use the cookie's automatic browser behaviour.

K-AI frontends running under .kai-studio.ai (K-AI Audit web app, K-AI Studio portal, K-AI Retrieval admin console, PICSOU dashboard) authenticate users via the kai_auth HttpOnly cookie issued by the central auth service at https://auth-api.kai-studio.ai. The cookie carries a signed JWT with the same format and signing key as OAuth 2.1 access tokens, so downstream services validate browser and MCP traffic identically.

Cookie properties

• HttpOnly — not readable from JavaScript (mitigates XSS token theft).

• Secure — sent only over TLS.

• SameSite=Lax — sent on top-level navigations, blocked on cross-site POST.

• Domain=.kai-studio.ai — shared across every subdomain.

• Path=/ — sent on every request to a *.kai-studio.ai host.

• Lifetime — 15 minutes, sliding (see below).

Sliding window refresh

Browser frontends keep the session alive by polling POST https://auth-api.kai-studio.ai/auth/cookie-refresh before the cookie expires. K-AI's own frontends (K-AI Audit web app, K-AI Studio portal, K-AI Retrieval admin console, PICSOU dashboard) do this automatically. If you build a custom frontend on *.kai-studio.ai, implement the same polling.

The refresh endpoint accepts the current kai_auth cookie (within a 5-minute grace period after expiry), reissues a JWT, and sets a fresh cookie on the response. There is no resource-side renewal middleware — every authenticated request relies on the cookie the client last received from /auth/cookie-refresh (or the initial login).

Logout

To end a session, call the central logout endpoint. The server clears the kai_auth cookie with Max-Age=0.

POST https://auth-api.kai-studio.ai/auth/cookie-logout

await fetch("https://auth-api.kai-studio.ai/auth/cookie-logout", {
  method: "POST",
  credentials: "include",
});

curl -X POST https://auth-api.kai-studio.ai/auth/cookie-logout \
  -b "kai_auth=<cookie-value>" \
  -c /tmp/cookies.txt

After logout, redirect the user to https://auth.kai-studio.ai/login (optionally with a ?next= parameter pointing back to your app).

Single sign-on across subdomains

Because the cookie is scoped to .kai-studio.ai, every first-party frontend — the K-AI Audit web app (audit.kai-studio.ai), the K-AI Studio portal (app.kai-studio.ai), the K-AI Retrieval admin console, and the PICSOU dashboard — receives it automatically. Users log in once on auth.kai-studio.ai and navigate across the suite without seeing another login screen or cross-domain redirect dance. The same cookie also satisfies the Audit and Retrieval APIs (api-audit.kai-studio.ai, api-retrieval.kai-studio.ai) when called from a browser context.

Not for backend pipelines

• Cookies are for browsers only. Backend integrations use API keys or OAuth 2.1 — see Choose your auth.