From 1640f076c857a06b9f38435ae4351d6627dafd83 Mon Sep 17 00:00:00 2001 From: Daniel Sousa Date: Wed, 8 Jul 2026 13:12:18 -0300 Subject: [PATCH 1/7] docs: add Users API reference page Document the option-gated Users API exposed by the api_key-role `users/manage-programmatic` grant (label "Users: Manage"): list users, invite a user, list/revoke pending invites, update and delete a user, and manage a user's subaccount mappings. Covers the prerequisites (the `allow_user_management_via_api` account option enabled by support, plus an admin attaching the grant via the web app), the invite-based-only creation flow and treating the invite token as a credential, the update field deny-list (password, tfa_enabled, is_sso, email), and the role-ceiling / last-admin / key-revocation constraints. Registered under the Accounts category in the table of contents. Closes SparkPost/developers.sparkpost.com#584 Part of SparkPost/access#121 Do not merge/publish until the feature ships. Implementation PRs: SparkPost/access#124, SparkPost/accusers-api#1294, SparkPost/auth-api#319. Claude-Session: https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU --- content/api/table-of-contents.json | 1 + content/api/users.apib | 425 +++++++++++++++++++++++++++++ 2 files changed, 426 insertions(+) create mode 100644 content/api/users.apib 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..f6836f7c --- /dev/null +++ b/content/api/users.apib @@ -0,0 +1,425 @@ +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. + +Note: This API is available only to accounts that have user management via API keys enabled. See Prerequisites below. Contact SparkPost support to request access. + +### Prerequisites + +Two conditions must both be met before an API key can call the Users API: + +1. **The account option `allow_user_management_via_api` must be enabled.** This option is enabled only by SparkPost support; it cannot be toggled through the API or the web app. Contact support to request it for your account. +2. **An admin must attach the `Users: Manage` grant to the API key.** The grant can only be added by an **admin** user through the web app's [API Keys page](https://app.sparkpost.com/account/api-keys). It cannot be attached by another API key. Only API keys carry this grant — it is an `api_key`-role grant. + +Requests made with a key that lacks the `Users: Manage` grant, or made on an account where the option is not enabled, are rejected with `403 Forbidden`. + +The Users: Manage grant is intentionally narrower than the user management available in the web app. It does not cover two-factor authentication, email verification, SCIM provisioning, or password endpoints, and it does 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`. +* **Restricted fields on update.** `password`, `tfa_enabled`, `is_sso`, and `email` cannot be changed through the API key. Sending any of `password`, `tfa_enabled`, or `is_sso` on an update is rejected with `403 Forbidden`; `email` is silently ignored. +* **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. + + `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. + + auth_migrated (boolean) - Internal flag indicating the user's authentication has been migrated. + + options (object) - User-level options, present only when set. + + link (object) - A link to the individual user resource. + + href (string) + + rel (string) + +### 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. + +### List Users [GET /v1/users] + +Returns the users on your account. Superuser accounts are never included, and users with hidden roles are omitted. + +The user identified by the API key's owner determines which users are visible; the key owner must be a user on the 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, + "auth_migrated": false, + "link": { + "href": "https://api.sparkpost.com/api/v1/users/ada", + "rel": "urn:msys:user" + } + }, + { + "name": "Grace Hopper", + "username": "grace", + "email": "grace@example.com", + "access": "reporting", + "is_sso": false, + "email_verified": true, + "tfa_enabled": true, + "auth_migrated": false, + "link": { + "href": "https://api.sparkpost.com/api/v1/users/grace", + "rel": "urn:msys:user" + } + } + ] + } + ++ Response 403 (application/json) + + { + "errors": [ + { + "message": "Forbidden" + } + ] + } + +### 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" + } + ] + } + +### List Pending Invites [GET /v1/users/pending-invites/all] + +Returns the invitations on your account that have not yet been accepted. + ++ 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" + } + ] + } + +### 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}] + +Updates an existing user. You may change `first_name`, `last_name`, `access_level` (and, for a `custom` role, `access_policies`), and `options`. + +The following fields cannot be changed through an API key: password, tfa_enabled, is_sso, and email. Including password, tfa_enabled, or is_sso in the request is rejected with 403 Forbidden; email is ignored. + +Changing `access_level` is subject to the [role ceiling](#header-constraints), and demoting the account's last `admin` is rejected with `400`. + ++ Data Structure + + first_name (string) - The user's first name. + + last_name (string) - The user's last name. + + access_level (enum) - The primary-account role to assign. + + `admin` + + `developer` + + `reporting` + + `templates` + + `custom` + + access_policies (array) - The policies to grant. Only valid when `access_level` is `custom`. + + options (object) - User-level options. + ++ Parameters + + username (required, string, `grace`) - The username of the user to update. + ++ Request (application/json) + + + Headers + + Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf + + + Body + + { + "first_name": "Grace", + "last_name": "Hopper", + "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 From dc60cb7c81e7b91dc13f65577eb03ec5db40d9d3 Mon Sep 17 00:00:00 2001 From: Daniel Sousa Date: Wed, 8 Jul 2026 16:13:57 -0300 Subject: [PATCH 2/7] docs: scrub internals and expand Users API page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove non-public details: the account option key, the internal auth_migrated user field, and the PUT restricted-fields enumeration. Prerequisites and the update endpoint are now worded positively (what is enabled / what is updatable) rather than naming internal config or forbidden fields. Add the invite lifecycle (3-day expiry, expired invites drop off the pending list automatically, no resend — re-invite instead, 429 when rate limited), the Retrieve a User and List a User's Subaccounts endpoints, and the canonical GET /v1/users/pending-invites listing (replacing the legacy /all variant). The Invite object now carries access_level and expires. Claude-Session: https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU --- content/api/users.apib | 130 ++++++++++++++++++++++++++++++++--------- 1 file changed, 101 insertions(+), 29 deletions(-) diff --git a/content/api/users.apib b/content/api/users.apib index f6836f7c..7c36ae3b 100644 --- a/content/api/users.apib +++ b/content/api/users.apib @@ -12,10 +12,10 @@ The Users API lets you list, invite, update, and remove the users on your accoun Two conditions must both be met before an API key can call the Users API: -1. **The account option `allow_user_management_via_api` must be enabled.** This option is enabled only by SparkPost support; it cannot be toggled through the API or the web app. Contact support to request it for your account. +1. **User management via API keys must be enabled on your account.** This is enabled only by SparkPost support. Contact support to request access for your account. 2. **An admin must attach the `Users: Manage` grant to the API key.** The grant can only be added by an **admin** user through the web app's [API Keys page](https://app.sparkpost.com/account/api-keys). It cannot be attached by another API key. Only API keys carry this grant — it is an `api_key`-role grant. -Requests made with a key that lacks the `Users: Manage` grant, or made on an account where the option is not enabled, are rejected with `403 Forbidden`. +Requests made with a key that lacks the `Users: Manage` grant, or made on an account where the feature is not enabled, are rejected with `403 Forbidden`. The Users: Manage grant is intentionally narrower than the user management available in the web app. It does not cover two-factor authentication, email verification, SCIM provisioning, or password endpoints, and it does not allow direct password-based user creation (see Invite a User). @@ -39,12 +39,11 @@ The following rules are enforced on every Users API request. They protect agains * **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`. -* **Restricted fields on update.** `password`, `tfa_enabled`, `is_sso`, and `email` cannot be changed through the API key. Sending any of `password`, `tfa_enabled`, or `is_sso` on an update is rejected with `403 Forbidden`; `email` is silently ignored. * **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). +Returned by [List Users](#header-list-users) and [Retrieve a User](#header-retrieve-a-user). + Data Structure: User + name (string) - The user's display name, derived from their first and last name. @@ -61,11 +60,7 @@ Returned by [List Users](#header-list-users). + 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. - + auth_migrated (boolean) - Internal flag indicating the user's authentication has been migrated. + options (object) - User-level options, present only when set. - + link (object) - A link to the individual user resource. - + href (string) - + rel (string) ### Invite object @@ -75,12 +70,24 @@ Returned by [List Pending Invites](#header-list-pending-invites). + 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. -### List Users [GET /v1/users] +### 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. -Returns the users on your account. Superuser accounts are never included, and users with hidden roles are omitted. +### List Users [GET /v1/users] -The user identified by the API key's owner determines which users are visible; the key owner must be a user on the account. +Returns the users on your account. + Request @@ -100,12 +107,7 @@ The user identified by the API key's owner determines which users are visible; t "access": "admin", "is_sso": false, "email_verified": true, - "tfa_enabled": false, - "auth_migrated": false, - "link": { - "href": "https://api.sparkpost.com/api/v1/users/ada", - "rel": "urn:msys:user" - } + "tfa_enabled": false }, { "name": "Grace Hopper", @@ -114,12 +116,7 @@ The user identified by the API key's owner determines which users are visible; t "access": "reporting", "is_sso": false, "email_verified": true, - "tfa_enabled": true, - "auth_migrated": false, - "link": { - "href": "https://api.sparkpost.com/api/v1/users/grace", - "rel": "urn:msys:user" - } + "tfa_enabled": true } ] } @@ -134,6 +131,44 @@ The user identified by the API key's owner determines which users are visible; t ] } +### Retrieve a User [GET /v1/users/{username}] + +Returns a single user by username. + ++ Parameters + + username (required, string, `grace`) - The username of the user to retrieve. + ++ Request + + + Headers + + Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf + Accept: application/json + ++ Response 200 (application/json) + + { + "results": { + "name": "Grace Hopper", + "username": "grace", + "email": "grace@example.com", + "access": "reporting", + "is_sso": false, + "email_verified": true, + "tfa_enabled": true + } + } + ++ 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). @@ -204,9 +239,19 @@ The response contains the invite `token`. ] } -### List Pending Invites [GET /v1/users/pending-invites/all] ++ Response 429 (application/json) -Returns the invitations on your account that have not yet been accepted. + { + "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 @@ -222,7 +267,9 @@ Returns the invitations on your account that have not yet been accepted. { "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "email": "newuser@example.com", - "from": "ada@example.com" + "from": "ada@example.com", + "access_level": "reporting", + "expires": 1720656000 } ] } @@ -254,9 +301,7 @@ Revokes a pending invitation so its registration link can no longer be used. ### Update a User [PUT /v1/users/{username}] -Updates an existing user. You may change `first_name`, `last_name`, `access_level` (and, for a `custom` role, `access_policies`), and `options`. - -The following fields cannot be changed through an API key: password, tfa_enabled, is_sso, and email. Including password, tfa_enabled, or is_sso in the request is rejected with 403 Forbidden; email is ignored. +Updates an existing user. Through this endpoint you can change the following fields: `first_name`, `last_name`, `access_level` (and, when `access_level` is `custom`, `access_policies`), and `options`. Changing `access_level` is subject to the [role ceiling](#header-constraints), and demoting the account's last `admin` is rejected with `400`. @@ -364,6 +409,33 @@ You cannot delete the user who owns the API key you are calling with, a user tha ] } +### List a User's Subaccounts [GET /v1/users/{username}/subaccounts] + +Returns the subaccounts a user has been granted access to, along with their access level on each. + ++ Parameters + + username (required, string, `grace`) - The username of the user. + ++ Request + + + Headers + + Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf + Accept: application/json + ++ Response 200 (application/json) + + { + "results": [ + { + "subaccount_id": 123, + "subaccount_name": "Joe's Garage", + "access_level": "subaccount_reporting", + "status": "active" + } + ] + } + ### 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. From 482e28a4f8141e834f8fd8c9cc44964f51d5e9f6 Mon Sep 17 00:00:00 2001 From: Daniel Sousa Date: Wed, 8 Jul 2026 17:55:43 -0300 Subject: [PATCH 3/7] docs: document Users: View grant and drop support-enablement step These docs publish at GA, after the account-option gate is removed, so there is no "enabled by SparkPost support" prerequisite at publish time; remove that wording and the contact-support banner. Document both grants: `Users: View` (read-only, GET endpoints) and `Users: Manage` (full management; required by every write endpoint). The only remaining prerequisite is that an admin attaches the grant to the key via the web app. Claude-Session: https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU --- content/api/users.apib | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/content/api/users.apib b/content/api/users.apib index 7c36ae3b..e4797082 100644 --- a/content/api/users.apib +++ b/content/api/users.apib @@ -6,18 +6,16 @@ description: Programmatically manage the users on your SparkPost account with an 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. -Note: This API is available only to accounts that have user management via API keys enabled. See Prerequisites below. Contact SparkPost support to request access. - ### Prerequisites -Two conditions must both be met before an API key can call the Users API: +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. -1. **User management via API keys must be enabled on your account.** This is enabled only by SparkPost support. Contact support to request access for your account. -2. **An admin must attach the `Users: Manage` grant to the API key.** The grant can only be added by an **admin** user through the web app's [API Keys page](https://app.sparkpost.com/account/api-keys). It cannot be attached by another API key. Only API keys carry this grant — it is an `api_key`-role grant. +* **`Users: View`** — read-only access, covering the `GET` endpoints only: [List Users](#header-list-users), [Retrieve a User](#header-retrieve-a-user), [List Pending Invites](#header-list-pending-invites), and [List a User's Subaccounts](#header-list-a-users-subaccounts). +* **`Users: Manage`** — full management. Every write endpoint (invite, update, delete, and the subaccount-mapping changes) requires this grant. -Requests made with a key that lacks the `Users: Manage` grant, or made on an account where the feature is not enabled, are rejected with `403 Forbidden`. +Requests made with a key that holds neither grant, or that attempt a write with only `Users: View`, are rejected with `403 Forbidden`. -The Users: Manage grant is intentionally narrower than the user management available in the web app. It does not cover two-factor authentication, email verification, SCIM provisioning, or password endpoints, and it does not allow direct password-based user creation (see Invite a User). +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 From d034522b2011b8253d9e3e8745f2eb4b5baf44eb Mon Sep 17 00:00:00 2001 From: Daniel Sousa Date: Thu, 9 Jul 2026 13:12:49 -0300 Subject: [PATCH 4/7] docs(users): document embedded subaccounts array, drop subaccounts GET Claude-Session: https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU --- content/api/users.apib | 65 ++++++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 28 deletions(-) diff --git a/content/api/users.apib b/content/api/users.apib index e4797082..048f3088 100644 --- a/content/api/users.apib +++ b/content/api/users.apib @@ -10,7 +10,7 @@ The Users API lets you list, invite, update, and remove the users on your accoun 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), [List Pending Invites](#header-list-pending-invites), and [List a User's Subaccounts](#header-list-a-users-subaccounts). +* **`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`. @@ -58,6 +58,17 @@ Returned by [List Users](#header-list-users) and [Retrieve a User](#header-retri + 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; when it is present, the top-level `access` 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. Returned only by [Retrieve a User](#header-retrieve-a-user). + + active + + suspended + + terminated + options (object) - User-level options, present only when set. ### Invite object @@ -133,6 +144,8 @@ Returns the users on your account. Returns a single user by username. +For a subaccount-scoped user, the response embeds a `subaccounts` array describing the subaccounts the user can access and their access level on each. When `subaccounts` is present, the top-level `access` and `subaccount_id` fields are omitted. + + Parameters + username (required, string, `grace`) - The username of the user to retrieve. @@ -157,6 +170,29 @@ Returns a single user by username. } } ++ Response 200 (application/json) + + A subaccount-scoped user. + + { + "results": { + "name": "Joe Mechanic", + "username": "joe", + "email": "joe@example.com", + "is_sso": false, + "email_verified": true, + "tfa_enabled": false, + "subaccounts": [ + { + "subaccount_id": 123, + "subaccount_name": "Joe's Garage", + "access_level": "subaccount_reporting", + "status": "active" + } + ] + } + } + + Response 404 (application/json) { @@ -407,33 +443,6 @@ You cannot delete the user who owns the API key you are calling with, a user tha ] } -### List a User's Subaccounts [GET /v1/users/{username}/subaccounts] - -Returns the subaccounts a user has been granted access to, along with their access level on each. - -+ Parameters - + username (required, string, `grace`) - The username of the user. - -+ Request - - + Headers - - Authorization: 14ac5499cfdd2bb2859e4476d2e5b1d2bad079bf - Accept: application/json - -+ Response 200 (application/json) - - { - "results": [ - { - "subaccount_id": 123, - "subaccount_name": "Joe's Garage", - "access_level": "subaccount_reporting", - "status": "active" - } - ] - } - ### 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. From 6c825772918d2b6c5461347aa6f22d6d337a1a92 Mon Sep 17 00:00:00 2001 From: Daniel Sousa Date: Thu, 9 Jul 2026 13:17:50 -0300 Subject: [PATCH 5/7] docs(users): tighten Retrieve a User lead-in Claude-Session: https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU --- content/api/users.apib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/api/users.apib b/content/api/users.apib index 048f3088..aaa443f0 100644 --- a/content/api/users.apib +++ b/content/api/users.apib @@ -144,7 +144,7 @@ Returns the users on your account. Returns a single user by username. -For a subaccount-scoped user, the response embeds a `subaccounts` array describing the subaccounts the user can access and their access level on each. When `subaccounts` is present, the top-level `access` and `subaccount_id` fields are omitted. +For a subaccount-scoped user, the response embeds the `subaccounts` array in place of the top-level `access` and `subaccount_id` fields. + Parameters + username (required, string, `grace`) - The username of the user to retrieve. From 98d338c57f63dc3e8c4e1986dbe9601d5fea36f5 Mon Sep 17 00:00:00 2001 From: Daniel Sousa Date: Thu, 9 Jul 2026 13:29:18 -0300 Subject: [PATCH 6/7] docs(users): split List vs Retrieve user shapes Retrieve a User returns first_name/last_name, access_level, created, updated, and an always-present subaccounts array (with status) - a different shape from the List Users item. Document them separately. Claude-Session: https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU --- content/api/users.apib | 60 +++++++++++++++++++++++++++++++++--------- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/content/api/users.apib b/content/api/users.apib index aaa443f0..350ead7b 100644 --- a/content/api/users.apib +++ b/content/api/users.apib @@ -41,13 +41,13 @@ The following rules are enforced on every Users API request. They protect agains ### User object -Returned by [List Users](#header-list-users) and [Retrieve a User](#header-retrieve-a-user). +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. + + access (enum) - The user's primary-account role. Empty for subaccount-scoped users. + `admin` + `developer` + `reporting` @@ -58,18 +58,49 @@ Returned by [List Users](#header-list-users) and [Retrieve a User](#header-retri + 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; when it is present, the top-level `access` and `subaccount_id` fields are omitted. + + 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. Returned only by [Retrieve a User](#header-retrieve-a-user). + + status (enum) - The subaccount's status. + active + suspended + terminated - + options (object) - User-level options, present only when set. ### Invite object @@ -142,9 +173,7 @@ Returns the users on your account. ### Retrieve a User [GET /v1/users/{username}] -Returns a single user by username. - -For a subaccount-scoped user, the response embeds the `subaccounts` array in place of the top-level `access` and `subaccount_id` fields. +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. @@ -160,13 +189,17 @@ For a subaccount-scoped user, the response embeds the `subaccounts` array in pla { "results": { - "name": "Grace Hopper", "username": "grace", + "first_name": "Grace", + "last_name": "Hopper", "email": "grace@example.com", - "access": "reporting", + "access_level": "reporting", "is_sso": false, "email_verified": true, - "tfa_enabled": true + "tfa_enabled": true, + "created": "2015-01-11T08:00:00.000Z", + "updated": "2018-04-11T08:00:00.000Z", + "subaccounts": [] } } @@ -176,12 +209,15 @@ For a subaccount-scoped user, the response embeds the `subaccounts` array in pla { "results": { - "name": "Joe Mechanic", "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, From 3e1955864e34b1d207912977fe9bf1ecea8fe0dc Mon Sep 17 00:00:00 2001 From: Daniel Sousa Date: Thu, 9 Jul 2026 14:20:29 -0300 Subject: [PATCH 7/7] docs(users): Update a User accepts only access_level/access_policies PUT now changes a user's role only; any other field in the request body is rejected with 403. Claude-Session: https://claude.ai/code/session_01AE1PyieVr2SdnCwF5A4xxU --- content/api/users.apib | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/content/api/users.apib b/content/api/users.apib index 350ead7b..207de2a3 100644 --- a/content/api/users.apib +++ b/content/api/users.apib @@ -371,21 +371,18 @@ Revokes a pending invitation so its registration link can no longer be used. ### Update a User [PUT /v1/users/{username}] -Updates an existing user. Through this endpoint you can change the following fields: `first_name`, `last_name`, `access_level` (and, when `access_level` is `custom`, `access_policies`), and `options`. +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 - + first_name (string) - The user's first name. - + last_name (string) - The user's last name. - + access_level (enum) - The primary-account role to assign. + + access_level (enum, required) - The primary-account role to assign. + `admin` + `developer` + `reporting` + `templates` + `custom` - + access_policies (array) - The policies to grant. Only valid when `access_level` is `custom`. - + options (object) - User-level options. + + 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. @@ -399,8 +396,6 @@ Changing `access_level` is subject to the [role ceiling](#header-constraints), a + Body { - "first_name": "Grace", - "last_name": "Hopper", "access_level": "developer" }