Access Control

Vendor dashboard: account membership and role

A vendor user's access to an account is an AccountMembership row joining userId and accountId, with a role of "admin", "member", or "viewer" (default "admin" — the user who creates an account is enrolled as its admin automatically). Every account-scoped route calls a shared requireOrgAccess(request, accountId, { minRole }) check after authenticating the vendor JWT: it looks up the AccountMembership row for that user and account, throws a 403 if there isn't one, and then compares the role that row carries against the minRole the route named — a second 403 if it falls short. The roles are ordered viewer < member < admin, and a route's minRole admits that role and every role above it.

The minRole argument is required, not defaulted, so a route cannot fail to state a tier and silently inherit the widest one — omitting it does not compile. What each tier can do:

The tiers are a real boundary, not a label: a viewer is refused on every write to an account they hold viewer on, and a member is refused on the admin capabilities above. The role is read from the database on every request rather than carried as a JWT claim, so the row is the authority and an already-issued token cannot outrank it. And enforcement fails closed on the column itself — the role column is a plain string with no database constraint, so a row holding anything other than those three names is refused for every tier, viewer included, rather than being read as the highest one.

API keys: scoped, hashed, account-bound (or platform-level)

Programmatic access uses an ApiKey record instead of a vendor session. A key is generated as ss_<64 hex chars> and shown to the vendor exactly once, at creation; only its SHA-256 keyHash and an 8-character keyPrefix (for display/identification) are stored — the raw key itself is never persisted. Presenting it via the X-API-Key header is checked against keyHash, and the key must be enabled and unexpired.

Each key also carries a scopes array, validated against a fixed allow-list:

connections:read      connections:write      connections:delete
agent-clients:read    agent-clients:write
webhooks:read         webhooks:write
observability:read
audit:read
platform:accounts:create   (platform-level keys only)
*  (all account-scoped scopes — never platform:*)

An unrecognized scope is rejected with a 400 on both create and update. Account-scoped keys are bound to a single accountId — using one against a different account's data fails requireOrgAccess() the same way an out-of-account vendor JWT would. A key is not mapped onto a membership role: it has no AccountMembership row, so minRole is not consulted on the key path at all. A key's authority is exactly two things — the account it was minted for, and the scopes it carries. Platform-level keys (accountId null) are a separate credential class: they may only hold platform:accounts:create, and they exist so a caller with zero accounts can bootstrap its first one via POST /api/v1/accounts. A platform-level key cannot be handed account-scoped scopes, and an account-scoped key cannot be handed platform:* — the two assignable sets are deliberately disjoint.

Admin portal: a third, separate path

The customer-facing admin portal doesn't use vendor roles or API scopes at all. A vendor generates a time-limited magic-link session (AdminPortalSession, tied to one account and one email); the token is stored only as a hash and presented back via the X-Admin-Token header, which the server consumes atomically on first use. This produces the "customer_admin" actor type seen in audit log entries, and is documented further in Magic Link Authentication.

Product-IdP-admin: one read, and nothing else

A vendor user can hold a ProductIdpAdmin row for one specific product. The row unlocks exactly one read — GET /api/v1/products/:id/handout for one named account — and nothing else. It grants no mutation, no provisioning, no secret, and no unfiltered listing; those stay platform-operator-only. A call made on this authority must name an account, so the role cannot be used to enumerate customers.

Two boundaries are worth stating exactly. The guard refuses an API key outright before it reads anything, so this authority can never be held by a credential left on a script host. And the role is mutually exclusive with account membership: a user who holds the row and any AccountMembership is refused with its own error code and its own audit line, re-decided on every request rather than trusted from grant time. The row is re-read per request, so revoking it takes effect on the holder's next call. See Identity Gateway for what the authority is for.

For the CORS, rate-limiting, and header hardening that sits in front of every one of them, see Security Overview.