---
id: w4/m4/t006
title: "Docs: authorization section in docs/ADR012-auth.md + env tables"
worker: worker4
status: done
estimate: 25m
depends_on: [w4/m4/t005]
---

## Objective

Extend the auth ADR with the authorization decision — why OpenFGA (vs roles-in-Postgres, vs Keto since Ory is already deployed), the model shape, the Checker seam contract (nil ⇒ allow-all, wired ⇒ fail closed), tuple lifecycle, and the w1/m2 tenant hand-off — grounded in what t001–t005 actually shipped.

## Context

- `docs/ADR012-auth.md` is the ADR to extend (it already covers the substrate + API keys); `docs/ADR006-bex-api.md#auth` gets a short authorization paragraph; root `CLAUDE.md` env table gains `BEX_OPENFGA_URL`.
- The Keto-vs-OpenFGA question deserves an honest paragraph: Keto would reuse the Ory family, but OpenFGA has the healthier ecosystem/CNCF track and first-class model DSL — record the actual reasoning.
- Prettier the changed markdown (`.pm/` is prettier-ignored, `docs/` is CI-checked).

## Steps

1. Write the authorization section (decision, model, seam semantics, ops: model/tuple apply scripts, fail-closed trade-off).
2. Env tables: root `CLAUDE.md`, `docs/ADR006-bex-api.md`; `operator/internal/api/CLAUDE.md` auth paragraph mention.
3. `npx prettier@3.4.2 --write` over the changed docs.

## Files

- `docs/ADR012-auth.md`, `docs/ADR006-bex-api.md`, `CLAUDE.md`, `operator/internal/api/CLAUDE.md`

## Acceptance criteria

- [ ] ADR covers decision + alternatives + seam contract + ops, each pointing at shipped files; prettier passes.

## Out of scope

- End-user documentation for tenant roles (post-w1/m2).
