# CivicRecap auth.md

How an agent gets access to CivicRecap. This document is self-contained
because there is deliberately no OAuth here: no authorization server, no
`/.well-known/oauth-protected-resource`, no dynamic client registration,
no API keys and no token endpoint. The credentials below are the whole
set, and every gated operation in the API declares which one it needs
(`components.securitySchemes` in https://www.civicrecap.com/openapi.json).

## Who this is for

Agents and non-browser callers reading the public record of California
civic meetings. Most of the read surface needs no credential at all:
an operation with no `security` in the OpenAPI description answers an
anonymous caller in full, and `GET /api/meetings/{id}` answers one with
a redacted teaser marked `"gated": true`.

## The credentials

- `session` — the `cr_session` cookie, minted by completing the hosted
  sign-in at https://www.civicrecap.com/signin. Accounts are free and open.
- `share_grant` — the `st=` token a signed-in reader's share link
  carries, minted by `GET /api/meetings/{id}/share` and good for that
  one meeting for 14 days. `POST /api/share/redeem` exchanges it once
  for the `cr_share` cookie.
- `media_signature` — the six-hour `sig=` signature on media URLs,
  minted complete by the clip, video, agenda and graphics endpoints and
  never constructed by a caller.
- `email_graphic` — the `eg=` grant a mailed briefing figure carries,
  minted into recap emails and nowhere else.
- `agent_token` — a `cr_agent_`-prefixed bearer token for the read-only
  operational surface at `/api/agent/*` (what is broken, the log, a
  task's stderr, the fleet, spending, the crawl, the settings). It is
  the one bearer token this API accepts, it is valid on that prefix and
  nowhere else, and it is not a session substitute: it carries no
  account and grants no write. An operator mints it by hand on
  /admin/agent-access for a named machine — there is no endpoint that
  issues one, so there is nothing here for an agent to request.

## Registration

Registration is the hosted sign-in, in a browser: a person (or a browser
an agent drives on their behalf) completes an email code at
https://www.civicrecap.com/signin and the session cookie that results is the
account credential. There is no programmatic registration endpoint, so
there is nothing here for an unattended agent to call — that is a
product decision, not an omission, and probing for one will only find
404s.

## What there is not

- No OAuth authorization server, so no `/.well-known/oauth-protected-resource`
  and no `/.well-known/oauth-authorization-server`: publishing scopes
  nothing can request would send an agent into a flow that does not exist.
- No API keys, and no bearer token but `agent_token` above — which an
  operator mints by hand and no caller can request.
- No downloads: clips and recordings are watched at their signed URLs or
  shared as links, never handed over as files.

## Machine-readable declarations

- https://www.civicrecap.com/openapi.json — the API, with `security` on every gated operation.
- https://www.civicrecap.com/.well-known/api-catalog — the RFC 9727 API catalog.
- https://www.civicrecap.com/llms.txt — what this site is, and where everything else lives.
- https://www.civicrecap.com/developers — the same story in prose, for a person.