# Authentication patterns

Pick the ONE pattern matching how a customer authorizes AO against
your platform:

1. **oauth** — you expose OAuth 2.0 Authorization Code with per-user
   tokens and refresh. The customer sees your consent screen. Provide:
   authorize + token endpoints, scopes, refresh semantics, and how AO
   registers its client (the dossier should say who creates the app).
2. **github_app** — an "install on org" app UX whose callback posts an
   installation id (GitHub Apps, Slack apps, marketplace-style
   installs). Provide: app creation/registration steps and the install
   callback contract.
3. **iam_trust** — cloud-principal trust (cross-account role, workload
   identity federation, service principal). The customer attaches a
   trust policy in their console and hands AO a role/principal
   reference — no secret material changes hands.
4. **credential_paste** — an API token created in your settings UI and
   pasted into AO. The fallback when there is no machine-driven flow.
   Strongly consider a pre-filled token-creation URL (a deep link that
   selects the right scopes) — it removes the most error-prone step.
5. **ingest** — you have no API for AO to call; instead you emit events
   to an AO-provided webhook URL with a shared secret. See the
   no-surface tracks if this is you.

If your platform supports more than one, prefer the one with the least
manual customer work: github_app ≻ oauth ≻ iam_trust ≻
credential_paste.