User Management

This guide provides an overview of how to manage Bandwidth users via the API.

note

These endpoints require your credential to have ACCOUNT_ADMIN scope. Before creating or updating users, you will also need the IDs for the roles and accounts you want to assign. Use the endpoints in the User Access Configuration section below to retrieve them.

User Access Configuration

A user's permissions in the Bandwidth Dashboard are determined by the accounts, roles, and accountScope assigned to them. These values are required on user creation and can be updated at any time.

Accounts

A comprehensive list of your accounts can be found via the Bandwidth accounts endpoint. You only need to specify the accountId in your user creation or update request.

Accounts endpoint:

GEThttps://api.bandwidth.com/api/v2/accounts

note

Your credential must have access to any account you want to add to or remove from a user. You cannot assign or remove accounts that your own credential does not have access to.

Roles

A comprehensive list of your roles can be found via the Bandwidth roles endpoint. You only need to specify the roleId in your user creation or update request.

Roles endpoint:

GEThttps://api.bandwidth.com/api/v1/roles

note

Your credential must have access to any role you want to add to or remove from a user. You cannot assign or remove roles that your own credential does not have access to.

Account Scopes

Account scope determines the level of access a user has to the accounts assigned to them.

Scope	Description
ACCOUNT	Standard access. The user can view and manage resources within their assigned accounts.
ACCOUNT_ADMIN	Administrative access. In addition to standard access, the user can manage other users and their account assignments.

Creating a User

See our API Reference for detailed information on creating users via the API.

POSThttps://api.bandwidth.com/api/v1/users

note

The basicAccess role is required for a user to sign in to the Bandwidth App.

Sample Request Body:

{
    "userId": "jdoe123",
    "email": "jdoe123@email.com",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+1234567890",
    "accountScope": "ACCOUNT",
    "accounts": ["123456", "654321"],
    "roles": ["basicAccess", "role-id"]
}

Updating a User

See our API Reference for more information on updating users via the API.

PATCHhttps://api.bandwidth.com/api/v1/users/{userId}

note

Providing roles or accounts in an update request overwrites the existing values — it does not append to them. Include all desired roles and accounts in each request.

Sample Request Body:

{
    "accountScope": "ACCOUNT_ADMIN",
    "accounts": ["123456", "654321"],
    "roles": ["basicAccess", "role-id2"],
    "status": "ACTIVE"
}

User Status Transitions

The following table shows the valid status transitions for each user state. Hover over a transition to see how to carry it out.

From / To	STAGED	PROVISIONED	ACTIVE	PASSWORD_EXPIRED	LOCKED_OUT	RECOVERY	SUSPENDED	DEPROVISIONED
STAGED	●		●					●
PROVISIONED		●	●					●
ACTIVE			●				●	●
PASSWORD_EXPIRED			●	●				●
LOCKED_OUT			●		●			●
RECOVERY			●			●		●
SUSPENDED			●				●	●
DEPROVISIONED			●					●

Key:     ● = Valid transition