Skip to main content
An accounts provider declares the member-admin actions it supports; the platform renders and routes them without knowing what any action means. The Members surface reads that declaration to offer page buttons and per-row menus, and a single invoke door performs one on demand. A provider adds, renames, or removes an action by changing its declaration alone — no platform code and no bespoke route moves with it.

Declared, not built in

A provider returns its actions as data, each one a small descriptor the platform treats generically:
  • id — the provider’s own token for the action. The platform never parses or branches on it; it only carries it back to the provider that declared it.
  • label — the wording shown in the UI, resolved to a plain string at the catalog door through the platform’s templated-text path, so it localizes like any other wording.
  • scope — where the action renders: page (acts on no existing row), member_row (acts on one member), or invite_row (acts on one outstanding invitation). A closed set every member view has a place for.
  • destructive — whether the surface asks the caller to confirm first.
  • input schema and result schema — the JSON Schema of what the action takes and what it returns. The platform renders a form from the input schema and a read-only view from the result schema; it reads no field of either.
Alongside its actions, a provider declares its own display name — one short, non-blank line that never changes while it runs. The catalog stamps that name on each of the provider’s descriptors, and the Members directory carries it on every member and invitation row the provider owns. The Members page shows it beside every page action and in a Provider column of its people and invitations tables, so actions and rows of different providers read apart. A provider whose declared display name is blank, not a string, or more than one line fails the boot. Because the platform holds only the descriptor, any accounts provider’s actions appear on the same Members surface with no platform change — the capability is part of the accounts contract, not a feature of one provider.

Two doors

Both doors live under the reserved /api/auth namespace and are admin-only:
  • GET /api/auth/member-actions lists the deployment-wide catalog — every registered provider’s declared actions, each as a descriptor with its rendered label, the display name of the provider that owns it, scope, destructive flag, and input and result schemas.
  • POST /api/auth/member-actions/invoke performs one action, named by its catalog key, against an optional target row, with an input body.
The catalog is what the Members page renders its buttons and menus from; the invoke door is what a button or menu item calls.

Opaque keys and handles

A caller never names a provider. The catalog gives each action an opaque action key, and each row in the Members directory carries an opaque routing handle. Both are tokens the platform mints and decodes to route a call back to the provider that owns the action and to the row it acts on; a caller echoes them, never parses them. To invoke, a caller sends the action key, the target row’s handle (omitted for a page action), and the input. The platform decodes the key to its provider and action, decodes the handle to its target, refuses a malformed token or a key and handle that name different providers with a 400, and hands the call to the provider.

Validation and typed failure

The input is validated against the action’s declared input schema before the provider runs. A declared field with the wrong type is a 422 that names the offending field paths; an unknown key is ignored. A provider reports a correctable failure as a typed error, which the door maps to a status — a conflicting state is a 409, an unknown target a 404, a bad request a 400 — so a caller can tell a correctable failure from a server fault instead of meeting an opaque 500. On success the platform serializes the provider’s result generically and reads no field of it: whatever the action produces — including a one-time value shown only once, such as a sign-in link — surfaces on the invoke response and nowhere else.

Member state stays platform-owned

A member’s disabled state and role are access-control facts the platform owns, not something a provider reports. A provider’s member record carries the principal id (or ids) the person holds; the Members operation joins those ids against the platform’s own records and takes each principal’s disabled state and the role it holds from there. A row exposes each principal’s state and two derived values: disabled is true only when every principal the person holds is disabled, so a person with any live principal still reads active; role is the one role every principal holds, and null when there is no single one — every principal’s access was set directly, or the principals hold different roles. A person whose logins hold different roles is listed with each login’s own role, never refused. A principal id a provider names that the platform does not hold is a loud failure, never a guessed state. An invitation holds no principal yet, so its role is the one the provider reports: the role the person will hold.

See also