Skip to main content

Consent API

Requires an admin bearer token in this phase (binding consent to a verified IdP identity is future work — see backend/app/schemas/consent.py).

POST /v1/consent​

The human act that roots a session's authority. Pins one immutable policy version for the whole session's lifetime.

Request body (ConsentCreate):

{
  "scope": "kb-search-agent",
  "user_sub": "user:alice",
  "ttl_seconds": 1800
}

scope: 1–255 chars. user_sub: 1–255 chars. ttl_seconds: optional, 60–86400 (default set by server config).

Response — 201 (ConsentRead):

{
  "session_id": "...",
  "root_grant": "<JWT — the hop-1 token>",
  "policy_version": 1,
  "scope": "kb-search-agent",
  "user_sub": "user:alice",
  "hop_budget": 4,
  "expires_at": "2026-09-22T13:00:00Z"
}

Errors:

StatusMeaning
404Unknown scope — no compiled policy exists
409policy_recompile_required — the compiled policy predates a required schema version; resubmit the manifest to recompile