> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/authentication/cookies.md).

# Cookies

{% hint style="warning" %}
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.
{% endhint %}

K-AI frontends running under `.kai-studio.ai` (K-AI Audit web app, K-AI Studio portal, K-AI Retrieval admin console, K-AI Consumption Monitoring System) 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, K-AI Consumption Monitoring System) 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`.

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

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

```bash
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 receives it automatically. The K-AI Studio portal (`app.kai-studio.ai`) hosts the Audit, Retrieval, and Governance surfaces alongside the K-AI Consumption Monitoring System. 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](/knowledge-ai/authentication/authentication.md#choose-your-auth).