Endpoint specs (api/)

One YAML spec per implemented endpoint, regenerated from the shipped code (Phases 1-4). The human-readable counterpart is docs/auth/api-reference.md; both describe the same surface, and the code is the source of truth for each. For operating the module as an agent, see .ai/skills/polaris/SKILL.md.

Layout

Directory	Endpoints
auth/	register, login, email verification, tokens, sessions, switch-org, me, jwks, invite acceptance
auth/password/	forgot / reset / change
auth/mfa/	TOTP/SMS/email enrollment + confirmation, the login gate, step-up, recovery codes, factor management
orgs/	organization lifecycle, members, invitations, roles
permissions/	the permission catalog
users/	user admin (read, update, disable, enable, delete)

Spec schema

# <METHOD> <path>: one-line summary.
endpoint:
  method: POST
  path: /auth/login
  summary: Password login
  tags: [auth]
  auth: public            # public | bearer | mfa_token; step-up-gated routes add `step_up: true`
  requires_permissions: [] # the domain's REQUIRES_PERMISSIONS, where declared
  rate_limit: login        # per-IP budget group; omitted when only the global per-user budget applies
  effect: write            # read | write | destructive (see docs/extraction/effects.md)
  receipt: true            # defaults to true for write/destructive, false for read

input:
  source: body             # body | path | query | none
  fields:                  # field: {type, rules} as the domain validates them
    email: { type: string, rules: [required, email, "max:320"] }

domain:
  class: Polaris\Http\Auth\LoginEndpoint         # the Endpoint the manifest loader routes to
  description: >
    What the endpoint does, as implemented.

output:
  status: 200
  example: { data: { ... } }   # the implemented envelope; types the response in OpenAPI and the TypeScript client
  # example_<variant>: { ... }  # a second shape the same endpoint answers (login's example_mfa_required)

errors:                        # every non-2xx the domain returns
  - { status: 401, code: invalid_credentials }

events: [user.logged_in]       # PSR-14 events emitted (docs/auth/events.md)

Response typing

polaris manifest --format=openapi types each success response from the spec’s example (JSON Schema by example, Polaris\Http\Manifest\ExampleSchema): every key shown is required, scalars take their JSON type, array items are merged (a key missing from some items is optional, one null in some is nullable), a value null everywhere is a nullable string, an empty array has untyped items, and example_<variant> keys become a oneOf. The generated TypeScript client (packages/client-ts) is typed from that, so keep the examples the shape the endpoint really answers.

Tooling

The bin/altair spec:scaffold / spec:lint commands (and their skill) ship with the host framework, not with this module; run them from a host checkout. Scaffolding emits the Action, Input DTO, Responder, Domain stub, test, route entry, and OpenAPI fragment for a spec. When an endpoint changes, update its spec, docs/auth/api-reference.md, and the functional tests together; the functional suite is what keeps these specs honest.