diff --git a/content/api/table-of-contents.json b/content/api/table-of-contents.json
index 29480c5b..506efb6d 100644
--- a/content/api/table-of-contents.json
+++ b/content/api/table-of-contents.json
@@ -42,6 +42,7 @@
"pages": [
"account.apib",
"subaccounts.apib",
+ "users.apib",
"data-privacy.apib"
]
},
diff --git a/content/api/users.apib b/content/api/users.apib
new file mode 100644
index 00000000..207de2a3
--- /dev/null
+++ b/content/api/users.apib
@@ -0,0 +1,535 @@
+FORMAT: 1A
+title: Users API
+description: Programmatically manage the users on your SparkPost account with an API key.
+
+# Group Users
+
+The Users API lets you list, invite, update, and remove the users on your account, and manage each user's subaccount access, using an API key rather than the web app.
+
+### Prerequisites
+
+To call the Users API, an API key must hold one of two grants, and an **admin** must attach the grant to the key through the web app's [API Keys page](https://app.sparkpost.com/account/api-keys). A grant cannot be attached by another API key. Both are `api_key`-role grants.
+
+* **`Users: View`** — read-only access, covering the `GET` endpoints only: [List Users](#header-list-users), [Retrieve a User](#header-retrieve-a-user), and [List Pending Invites](#header-list-pending-invites).
+* **`Users: Manage`** — full management. Every write endpoint (invite, update, delete, and the subaccount-mapping changes) requires this grant.
+
+Requests made with a key that holds neither grant, or that attempt a write with only `Users: View`, are rejected with `403 Forbidden`.
+
+These grants are intentionally narrower than the user management available in the web app. They do not cover two-factor authentication, email verification, SCIM provisioning, or password endpoints, and they do not allow direct password-based user creation (see Invite a User).
+
+### Roles
+
+When you invite or update a user you assign a **role** through the `access_level` field. The primary-account roles are:
+
+| Role | Description |
+|-------------|-------------------------------------------------------------|
+| `admin` | Full access to the account, including user and billing management. |
+| `developer` | Access to sending and configuration APIs, without account administration. |
+| `reporting` | Read-only access to reporting and analytics. |
+| `templates` | Access limited to managing templates. |
+| `custom` | A role whose permissions are defined by the `access_policies` you supply. |
+
+Subaccount access levels (used only in the `subaccounts` array and in the subaccount-mapping endpoints) are `subaccount_reporting` and `subaccount_developer`.
+
+### Constraints
+
+The following rules are enforced on every Users API request. They protect against privilege escalation and account lockout:
+
+* **Role ceiling.** You can never create or invite a user, or raise a user to a role, more privileged than the role of the user who owns the API key. An admin-owned key can assign up to `admin`; a key owned by a less-privileged user is bounded by that user's role.
+* **Last admin protection.** The last `admin` on an account cannot be deleted or demoted through the API. Such a request is rejected with `400`.
+* **Key revocation on owner deletion.** If the admin user who owns a key holding the `Users: Manage` grant is deleted, that key is revoked rather than reassigned to another user.
+
+### User object
+
+Returned by [List Users](#header-list-users).
+
++ Data Structure: User
+ + name (string) - The user's display name, derived from their first and last name.
+ + username (string) - Unique username that identifies the user.
+ + email (string) - The user's email address.
+ + access (enum) - The user's primary-account role. Empty for subaccount-scoped users.
+ + `admin`
+ + `developer`
+ + `reporting`
+ + `templates`
+ + `custom`
+ + access_policies (array) - The policies granted to the user when `access` is `custom`.
+ + is_sso (boolean) - Whether the user signs in via single sign-on.
+ + email_verified (boolean) - Whether the user has verified their email address.
+ + tfa_enabled (boolean) - Whether the user has two-factor authentication enabled.
+ + subaccount_id (number) - The subaccount the user is scoped to, if any.
+ + subaccounts (array) - The subaccounts a subaccount-scoped user has access to, and their access level on each. Present only for subaccount-scoped users.
+ + (object)
+ + subaccount_id (number) - The subaccount ID.
+ + access_level (enum) - The user's access level on the subaccount.
+ + `subaccount_reporting`
+ + `subaccount_developer`
+ + subaccount_name (string) - The subaccount's display name.
+ + options (object) - User-level options, present only when set.
+
+### Retrieved user object
+
+Returned by [Retrieve a User](#header-retrieve-a-user). This is a richer shape than the [User object](#header-user-object) returned by List Users: it has `first_name` and `last_name` in place of `name`, uses `access_level` for the primary-account role, and adds `created`, `updated`, and an always-present `subaccounts` array.
+
++ Data Structure: RetrievedUser
+ + username (string) - Unique username that identifies the user.
+ + first_name (string) - The user's first name.
+ + last_name (string) - The user's last name.
+ + email (string) - The user's email address.
+ + access_level (enum) - The user's primary-account role. Omitted for subaccount-scoped users.
+ + `admin`
+ + `developer`
+ + `reporting`
+ + `templates`
+ + `custom`
+ + access_policies (array) - The policies granted to the user when `access_level` is `custom`.
+ + subaccount_id (number) - The subaccount the user is scoped to, if any. Omitted when `subaccounts` is non-empty.
+ + is_sso (boolean) - Whether the user signs in via single sign-on.
+ + email_verified (boolean) - Whether the user has verified their email address.
+ + tfa_enabled (boolean) - Whether the user has two-factor authentication enabled.
+ + options (object) - User-level options, present only when set.
+ + created (string) - ISO 8601 timestamp of when the user was created.
+ + updated (string) - ISO 8601 timestamp of when the user was last updated.
+ + subaccounts (array) - The subaccounts the user has access to, and their access level on each. Always present; an empty array for a user with no subaccount mappings. When it is non-empty, the top-level `access_level` and `subaccount_id` fields are omitted.
+ + (object)
+ + subaccount_id (number) - The subaccount ID.
+ + subaccount_name (string) - The subaccount's display name.
+ + access_level (enum) - The user's access level on the subaccount.
+ + `subaccount_reporting`
+ + `subaccount_developer`
+ + status (enum) - The subaccount's status.
+ + active
+ + suspended
+ + terminated
+
+### Invite object
+
+Returned by [List Pending Invites](#header-list-pending-invites).
+
++ Data Structure: Invite
+ + id (string) - Unique ID for the pending invite. Use it to revoke the invite.
+ + email (string) - The email address the invite was sent to.
+ + from (string) - The email address of the user who created the invite.
+ + access_level (enum) - The role the invited user will be assigned when they register.
+ + `admin`
+ + `developer`
+ + `reporting`
+ + `templates`
+ + `custom`
+ + expires (number) - Unix timestamp, in epoch seconds, at which the invitation expires.
+
+### Invite lifecycle
+
+* **Invitations expire after 3 days.** Once an invitation expires, its registration link no longer works.
+* **Expired invitations are removed automatically.** They stop appearing in [List Pending Invites](#header-list-pending-invites) once they expire; you do not need to clean them up.
+* **There is no resend.** To give someone another chance to register, [invite the same email address again](#header-invite-a-user). This creates a new, independent invitation with its own token and expiry; the earlier invitation keeps working until it expires or you [revoke it](#header-revoke-a-pending-invite).
+* **Invite creation is rate limited.** If you create invitations too quickly, requests are rejected with `429 Too Many Requests`. Wait before retrying.
+
+### List Users [GET /v1/users]
+
+Returns the users on your account.
+
++ Request
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+ Accept: application/json
+
++ Response 200 (application/json)
+
+ {
+ "results": [
+ {
+ "name": "Ada Lovelace",
+ "username": "ada",
+ "email": "ada@example.com",
+ "access": "admin",
+ "is_sso": false,
+ "email_verified": true,
+ "tfa_enabled": false
+ },
+ {
+ "name": "Grace Hopper",
+ "username": "grace",
+ "email": "grace@example.com",
+ "access": "reporting",
+ "is_sso": false,
+ "email_verified": true,
+ "tfa_enabled": true
+ }
+ ]
+ }
+
++ Response 403 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "Forbidden"
+ }
+ ]
+ }
+
+### Retrieve a User [GET /v1/users/{username}]
+
+Returns a single user by username. The response uses the [Retrieved user object](#header-retrieved-user-object) shape, which differs from the [User object](#header-user-object) returned by List Users.
+
++ Parameters
+ + username (required, string, `grace`) - The username of the user to retrieve.
+
++ Request
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+ Accept: application/json
+
++ Response 200 (application/json)
+
+ {
+ "results": {
+ "username": "grace",
+ "first_name": "Grace",
+ "last_name": "Hopper",
+ "email": "grace@example.com",
+ "access_level": "reporting",
+ "is_sso": false,
+ "email_verified": true,
+ "tfa_enabled": true,
+ "created": "2015-01-11T08:00:00.000Z",
+ "updated": "2018-04-11T08:00:00.000Z",
+ "subaccounts": []
+ }
+ }
+
++ Response 200 (application/json)
+
+ A subaccount-scoped user.
+
+ {
+ "results": {
+ "username": "joe",
+ "first_name": "Joe",
+ "last_name": "Mechanic",
+ "email": "joe@example.com",
+ "is_sso": false,
+ "email_verified": true,
+ "tfa_enabled": false,
+ "created": "2015-01-11T08:00:00.000Z",
+ "updated": "2018-04-11T08:00:00.000Z",
+ "subaccounts": [
+ {
+ "subaccount_id": 123,
+ "subaccount_name": "Joe's Garage",
+ "access_level": "subaccount_reporting",
+ "status": "active"
+ }
+ ]
+ }
+ }
+
++ Response 404 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "User does not exist"
+ }
+ ]
+ }
+
+### Invite a User [POST /v1/users/invite]
+
+There is no direct, password-based user creation through the API — users are created by **invitation** only. This endpoint creates an invitation and emails the invitee a registration link; the invitee completes registration through that link and sets their own password. The invited user's role is set by `access_level` and is bounded by the [role ceiling](#header-constraints).
+
+Provide `access_level` for a primary-account user, or `subaccounts` to invite a subaccount-scoped user. When `subaccounts` is supplied, a top-level `access_level` is not required.
+
+The response contains the invite `token`.
+
+Treat the invite token as a credential. Anyone who holds the token can complete registration as the invited user. Invited users normally complete registration through the emailed link, so you do not need to handle the token yourself; if you do capture it, store and transmit it as securely as you would a password, and never log or share it.
+
++ Data Structure
+ + email (string, required) - Email address of the person to invite. Max length: 512 characters.
+ + access_level (enum) - The primary-account role to assign. Required unless `subaccounts` is supplied.
+ + `admin`
+ + `developer`
+ + `reporting`
+ + `templates`
+ + `custom`
+ + access_policies (array) - The policies to grant. Only valid when `access_level` is `custom`.
+ + subaccounts (array) - Invite the user with access to one or more subaccounts instead of the primary account. Between 1 and 25 entries.
+ + (object)
+ + subaccount_id (number, required) - The subaccount ID.
+ + access_level (enum, required) - The subaccount access level.
+ + `subaccount_reporting`
+ + `subaccount_developer`
+
++ Request (application/json)
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+
+ + Body
+
+ {
+ "email": "newuser@example.com",
+ "access_level": "reporting"
+ }
+
++ Response 200 (application/json)
+
+ {
+ "results": {
+ "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+ "token": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
+ }
+ }
+
++ Response 400 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "email is a required parameter",
+ "param": "email",
+ "value": null
+ }
+ ]
+ }
+
++ Response 403 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "Forbidden"
+ }
+ ]
+ }
+
++ Response 429 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "Too many invite requests. Please try again later."
+ }
+ ]
+ }
+
+### List Pending Invites [GET /v1/users/pending-invites]
+
+Returns the invitations on your account that have not yet been accepted. Expired invitations are not included.
+
++ Request
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+ Accept: application/json
+
++ Response 200 (application/json)
+
+ {
+ "results": [
+ {
+ "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
+ "email": "newuser@example.com",
+ "from": "ada@example.com",
+ "access_level": "reporting",
+ "expires": 1720656000
+ }
+ ]
+ }
+
+### Revoke a Pending Invite [DELETE /v1/users/pending-invites/{id}]
+
+Revokes a pending invitation so its registration link can no longer be used.
+
++ Parameters
+ + id (required, string, `3f2504e0-4f89-41d3-9a0c-0305e82c3301`) - The invite ID from [List Pending Invites](#header-list-pending-invites).
+
++ Request
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+
++ Response 204
+
++ Response 404 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "User invite ID does not exist"
+ }
+ ]
+ }
+
+### Update a User [PUT /v1/users/{username}]
+
+Changes a user's role. The request accepts only `access_level` (and `access_policies` when `access_level` is `custom`); a request that contains any other field is rejected with `403 Forbidden`.
+
+Changing `access_level` is subject to the [role ceiling](#header-constraints), and demoting the account's last `admin` is rejected with `400`.
+
++ Data Structure
+ + access_level (enum, required) - The primary-account role to assign.
+ + `admin`
+ + `developer`
+ + `reporting`
+ + `templates`
+ + `custom`
+ + access_policies (array) - The policies to grant. Required when `access_level` is `custom`, and not allowed otherwise.
+
++ Parameters
+ + username (required, string, `grace`) - The username of the user to update.
+
++ Request (application/json)
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+
+ + Body
+
+ {
+ "access_level": "developer"
+ }
+
++ Response 200 (application/json)
+
+ {
+ "results": {
+ "message": "Successfully modified user grace"
+ }
+ }
+
++ Response 400 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "Cannot change the access level of the last admin user on the account."
+ }
+ ]
+ }
+
++ Response 403 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "Forbidden"
+ }
+ ]
+ }
+
+### Delete a User [DELETE /v1/users/{username}]
+
+Deletes a user from your account.
+
+You cannot delete the user who owns the API key you are calling with, a user that belongs to a different account, or the account's last `admin`.
+
++ Parameters
+ + username (required, string, `grace`) - The username of the user to delete.
+
++ Request
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+
++ Response 204
+
++ Response 400 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "Cannot delete the last admin user on the account."
+ }
+ ]
+ }
+
++ Response 403 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "Forbidden"
+ }
+ ]
+ }
+
++ Response 404 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "User does not exist"
+ }
+ ]
+ }
+
+### Add a Subaccount Mapping [POST /v1/users/{username}/subaccounts]
+
+Grants a user access to a subaccount at the given access level. If the user already has access to the subaccount, the access level is updated.
+
++ Data Structure
+ + subaccount_id (number, required) - The subaccount to grant access to.
+ + access_level (enum, required) - The access level to grant on the subaccount.
+ + `subaccount_reporting`
+ + `subaccount_developer`
+
++ Parameters
+ + username (required, string, `grace`) - The username of the user.
+
++ Request (application/json)
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+
+ + Body
+
+ {
+ "subaccount_id": 123,
+ "access_level": "subaccount_reporting"
+ }
+
++ Response 200 (application/json)
+
+ {
+ "results": {
+ "message": "Subaccount access granted"
+ }
+ }
+
++ Response 400 (application/json)
+
+ {
+ "errors": [
+ {
+ "message": "access_level must be one of: subaccount_reporting, subaccount_developer"
+ }
+ ]
+ }
+
+### Remove a Subaccount Mapping [DELETE /v1/users/{username}/subaccounts/{subaccountId}]
+
+Removes a user's access to a subaccount.
+
++ Parameters
+ + username (required, string, `grace`) - The username of the user.
+ + subaccountId (required, number, `123`) - The subaccount to remove access to.
+
++ Request
+
+ + Headers
+
+ Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf
+
++ Response 204