Document the Users API (User Management via API Keys)

[danielfsousa]

Part of epic SparkPost/access#121. Blocked on the feature shipping (grant + accusers-api + auth-api sub-issues).

The public API reference (content/api/*.apib) currently has no Users API page (and no API Keys API page — that surface is also option-gated/beta). Once user management via API keys ships, document the newly exposed surface.

Work items

• New content/api/users.apib page covering the endpoints exposed by the users/manage-programmatic grant:
  • GET /api/v1/users — list users
  • POST /api/v1/users/invite — invite a user (creation is invite-based; there is no direct password-based create via API)
  • GET /api/v1/users/pending-invites/all / DELETE /api/v1/users/pending-invites/:id — list/revoke pending invites
  • PUT /api/v1/users/:username — update a user (note: password, tfa_enabled, is_sso, and email are not updatable via API key)
  • DELETE /api/v1/users/:username — delete a user
  • POST /api/v1/users/:username/subaccounts / DELETE /api/v1/users/:username/subaccounts/:subaccountId — subaccount mappings
• Add the page to content/api/table-of-contents.json
• Prerequisites section: the account option allow_user_management_via_api must be enabled by SparkPost support, and only an admin can attach the Users: Manage grant to an API key (via the web UI)
• Document invite semantics: the invite response contains the invite token; treat it as a credential. Invited users complete registration via the emailed link
• Document constraints: role assignment is bounded by the key owner's role; the last admin of an account cannot be deleted or demoted via API; keys with this grant are revoked if their owning admin is deleted