docs: add Users API reference page

[danielfsousa]

Summary

Adds a public API reference page for the Users API — the endpoints exposed by the option-gated, api_key-role user-management grants that let an API key manage the users on an account.

New page content/api/users.apib, registered under the Accounts category in content/api/table-of-contents.json (after subaccounts.apib).

Everything in the .apib is public. Implementation-internal details are intentionally kept out of the page and captured in Reviewer notes below instead.

Endpoints documented

• GET /api/v1/users — list users
• GET /api/v1/users/:username — retrieve a user
• POST /api/v1/users/invite — invite a user (creation is invite-based only)
• GET /api/v1/users/pending-invites — list pending invites (canonical path)
• DELETE /api/v1/users/pending-invites/:id — revoke a pending invite
• PUT /api/v1/users/:username — update a user
• DELETE /api/v1/users/:username — delete a user
• POST /api/v1/users/:username/subaccounts / DELETE /api/v1/users/:username/subaccounts/:subaccountId — manage subaccount mappings

The read-side GET /api/v1/users/:username/subaccounts endpoint was dropped per design review; a user's subaccount access is now documented as the subaccounts array embedded in user objects (see Reviewer notes).

Also covered

• Prerequisites / grants: an API key needs one of two api_key-role grants, attached by an admin through the web app (never by another API key): Users: View for read-only access (the GET endpoints) or Users: Manage for full management (required by every write endpoint). No account-option / support-enablement step is documented — see the GA rollout note under Reviewer notes.
• Invite semantics and lifecycle: creation is invite-based only (no password-based create via API); the response returns the invite token, documented as a credential. Invitations expire after 3 days; expired invites drop off the pending list automatically; there is no resend (re-invite the same email to create a new independent invitation); invite creation is rate limited (429).
• Update endpoint is role-only: the request accepts only access_level (and access_policies when access_level is custom); any other field is rejected with 403.
• Constraints: role ceiling bounded by the key owner's role; the last admin cannot be deleted or demoted; keys holding a grant are revoked if their owning admin is deleted; two-factor, email-verification, SCIM, and password endpoints are out of scope.

Reviewer notes (not in public docs)

These are the implementation-internal details behind the public wording, for reviewer context only. They are deliberately not in the .apib:

• GA rollout / no option-gate wording. These docs are slated to publish at GA, after the account-option gate has been removed. So at publish time there is no "must be enabled by SparkPost support" step, and the page intentionally omits any account-option or contact-support mention. Until GA, the feature is gated by the account option allow_user_management_via_api (set only by SparkPost support) — that gate is expected to be gone by the time these docs go live.
• PUT allow-list (role-only), supersedes the deny-list. Per design decision, a programmatic PUT /users/:username accepts only access_level (plus access_policies when access_level is custom); any other field in the body is rejected with 403. This replaces the earlier deny-list approach (reject only password/tfa_enabled/is_sso/email, allow names/options through) — first_name/last_name/options are no longer editable via the API. The web UI is unaffected and retains full user editing. The page documents this positively (lists the accepted fields) rather than enumerating forbidden ones.
• Invite rate-limit internals. The 429 is driven by inviteThrottle (config.emailThrottling.invite): maxPerRecipient = 3, maxPerRequester = 20, over a ttl of 3600s (1-hour window). The public docs intentionally omit these numbers.
• Invite expiry source. The documented 3-day expiry is config.emailInvite.ttl = 259200s. Expired invites are filtered out of the listing (invite-dynamo.getInvites isExpired check) and DynamoDB TTL reaps the records.
• Dropped subaccounts GET. The GET /api/v1/users/:username/subaccounts endpoint was dropped per design review. A user's subaccount access is documented instead via the subaccounts array embedded in user objects (see next note).
• List vs Retrieve response shapes (pre-existing divergence, documented as-is). List Users and Retrieve a User return different shapes — pre-existing platform behavior (lib/models/users.js formatUser for List vs getUserByUsername + lookUpUser for Retrieve). The page documents them as two objects: User object (List) and Retrieved user object (Retrieve).
  • List Users item: name, username, access (enum; empty for subaccount-scoped users — nothing is removed top-level), access_policies, email, is_sso, email_verified, tfa_enabled, subaccount_id, last_login, options (only when set). Mapped users additionally get subaccounts: [{subaccount_id, access_level, subaccount_name}] — 3 fields, no status.
  • Retrieve a User: no name and no access; instead first_name, last_name, access_level (omitted entirely for subaccount-scoped users), plus created, updated, and an always-present subaccounts array ([{subaccount_id, subaccount_name, access_level, status}], empty for users with no mappings). When subaccounts is non-empty, top-level access_level and subaccount_id are omitted.
  • Retrieve carries additional internal fields we deliberately do NOT document in the public .apib: customer, cookie_consent, tou, tou_auto_accept, creation_params, auth_migrated, auth_connection, tokens (API-key IDs, not secrets), and customer_id inside each subaccounts entry.
  • Open question: last_login is returned by List Users but the page does not document it (I could not verify its type/format). Confirm whether it should be added and I will document it.

Verification status

Request/response shapes and error bodies were verified against the accusers-api source (resources/user-controller.js, resources/user-endpoints.js, lib/validator/*, lib/models/*, config/default.json) and the hardening PR SparkPost/accusers-api#1294, and the grant patterns/labels against @sparkpost/access (lib/token-access.js) and access PR SparkPost/access#124.

Verified against current code: list users, invite (request/response incl. token, 400, 429), revoke invite, update user (updatable fields, Successfully modified user <username>, last-admin 400), delete user, add/remove subaccount mapping, the invite lifecycle facts (3-day TTL, expired-invite filtering, throttle → 429), and the existing role-ceiling / last-admin / key-revocation constraints. The Users: View grant (label "Users: View", read-only GET surface: list, single-user, pending invites) is present in the access users-manage-programmatic working branch.

Could NOT yet verify against the pushed PR #1294 / access #124 — documented per the agreed spec and flagged as forthcoming. As of their latest pushes, the pushed PRs don't yet contain these; they line up with the accusers-api work items still in progress (retrieve-user hardening, embedded subaccounts array, pending-invites enrichment + canonical alias, PUT allow-list) and the access grant additions:

• Users: View grant — defined in the access working branch but not yet in the pushed access Add redirects for subaccounts docs changes #124 diff. Confirm it ships in the release.
• GET /api/v1/users/:username grant coverage and a grant-scoped response shape. The page documents the detailed getUserByUsername/lookUpUser shape (first_name, last_name, access_level, created, updated, always-present subaccounts), with the internal fields (tokens, auth_connection, customer, etc. — see Reviewer notes) deliberately omitted. Confirm the grant-scoped response exposes only the documented fields and none of the internal ones.
• Embedded subaccounts array (replaces the dropped GET /api/v1/users/:username/subaccounts route). Retrieve a User: always present, entries {subaccount_id, subaccount_name, access_level, status}, top-level access_level/subaccount_id omitted when non-empty. List Users: slimmer {subaccount_id, access_level, subaccount_name}, no status, present only for mapped users. Confirm both grant-scoped user responses match these shapes.
• GET /api/v1/users/pending-invites canonical path — only /pending-invites/all exists today. Confirm the canonical path is added to the route and both grants.
• Invite object access_level + expires (epoch seconds) — the current listing returns only {id, email, from}. Confirm the enriched fields.
• PUT allow-list (role-only) — the endpoint must accept only access_level/access_policies and reject every other field with 403 (supersedes the earlier password/tfa_enabled/is_sso/email deny-list, which allowed names/options through). Confirm the allow-list is enforced for programmatic callers.
• Users: Manage GET coverage — the manage grant's current get_grants cover only /users and /pending-invites/all; the single-user GET is covered by Users: View. Confirm manage keys can also reach those read endpoints (or that the docs should scope those reads to Users: View).

⚠️ Do not merge/publish until the feature ships

This documents an unreleased feature. Hold until the implementation ships:

• SparkPost/access#124 (grants, @sparkpost/access 4.13.0)
• SparkPost/accusers-api#1294 (endpoint hardening)
• SparkPost/auth-api#319 (grant enforcement)

Closes #584
Part of SparkPost/access#121

https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU