# Read19 API authentication and permissions

Read19 uses separate credential types so an integration receives only the authority needed for its job.

## Analysis key: kg_live_

An analysis key has the fixed role `analysis` with two permissions: `analysis:write` and `usage:read`.

- It can call `POST /v1/analyze`.
- It can call `GET /v1/usage`.
- It can open `wss://read19.com/v1/katago` with the analysis key in the `Authorization: Bearer <kg_live_...>` handshake header.
- It cannot read or change the account, billing, community, operator, or administration surfaces.
- Create and revoke analysis keys from the signed-in account console or the official Read19 CLI.
- The secret is shown once. Store it as a secret and never put it in a URL. Legacy GUI integrations that cannot set a handshake header should use the generated compatibility URL and treat the entire URL as a credential.

## Account session: kg_session_

An account session is a user-authorized credential used by the native client and CLI for account management. It is not accepted as an analysis key and cannot call the KataGo analysis endpoints.

The official CLI obtains it through a one-time browser approval flow. Headless password login is available, but callers must pipe the password or use a protected environment variable rather than place it on the command line.

## Browser session

The Web account console uses an HttpOnly, Secure, SameSite=Lax cookie. Mutating browser requests must come from the Read19 origin.

## Operator access

Operations endpoints are not part of the public API. They require a separately approved operator identity and Cloudflare Access. Customer analysis keys and account sessions cannot reach them.

## Least-privilege guidance

Use an analysis key for KataGo automation. Use an account session only while the user is managing keys, usage, or billing history. Never give an agent an operator credential for ordinary analysis.

See the machine-readable security schemes and per-operation requirements in https://read19.com/openapi.json.