Manage User Accounts

/v1/users/username

This document covers:

The WhatsApp Business API client has a default account — the username of the account is admin and the password is secret. This account cannot be removed or deleted from the system. For security reasons, you are required to change the admin password immediately.

Only the admin account is used to manage accounts, that is actions such as creating or removing users. If you forget your password, please contact Direct Support for assistance with resetting it.

Creating a User Account

The admin account is the only account that can create and delete users, so use the admin account only for this purpose as a best practice. You should create user accounts and use them to manage your WhatsApp Business API Clients.

To create an account for a user within your business who can access the WhatsApp Business API, send the username and password to the WhatsApp Business API Client using the users endpoint. It validates the username and password and creates a new account if one does not already exist for that username. The password is processed with a one-way hash and stored in a data volume. Both username and password are required parameters.

Request

To create a user, send a request such as the one shown in the following example:

POST /v1/users
Authorization: Bearer your-auth-token

{
  "username": "username",
  "password": "password"
}

Parameters

NameRequiredDescription

username

Yes

Must be a minimum of 4 characters and a maximum of 32 characters.
Establish a template for username, such as first initial and last name, to avoid creating multiple accounts for the same person.

password

Yes

Must be a minimum of 8 characters and a maximum of 64 characters.

Authorization

Yes

Authentication token for the administrator who is running the request. See Login and Authentication — Tokens documentation for more information.

Response

If the request is successful and a user account is created, you will receive an HTTP status code of 201 Created and the following payload:

{
  "users": [{
     "username": "username"
  }]
}

If the request is not successful, you will receive an HTTP status code, along with a WhatsApp error code. If you submit a duplicate username, the error response will look like this:

{
  "errors": [{
    "code": 1014,
    "title": "Internal error",
    "details": "Unable to create user. Already exist?"
  }]
}

Some likely errors:

HTTP Status CodeReason

400

  • Password is too short (less than 8 characters) or too long (greater than 64 characters).
  • Username is too short (fewer than 4 characters) or too long (greater than 32 characters)

Submit the request again with an appropriate length username/password.

403

You are not using the admin account to create the user account.

500

Unable to create the account, possibly because it already exists.

If there are other errors in the response, refer to the following sources for more information:

Changing a User Password

The WhatsApp Business API client has a default account — the username of the account is admin and the password is secret. This account cannot be removed or deleted from the system. For security reasons, you are required to change the admin password immediately. See the Login and Authentication documentation for more information on logging in for the first time.

A user with the role of ROLE_ADMIN can update the password associated with user accounts with roles of ROLE_ADMIN and ROLE_USER. Individual users can also update the password for their own accounts. Updating a user account password does not invalidate any access tokens associated with the user. Currently, only user admin has ROLE_ADMIN; other users have ROLE_USER.

Request

To update the password for an account, provide the Bearer token along with the username and new password.

PUT /v1/users/username
Authorization: Bearer your-auth-token
   
{
  "password": "new-password"
}

Response

If successful, the password associated with the username is updated. The HTTP status code 200 OK is returned, along with a payload similar to the following:

{
   "users": [{
      "username": "username"
   }]
}

If not successful, the response may contain one of the following error codes:

HTTP Status CodeReason

400

Bad Request

401

Unable to validate the credentials

404

Account does not exist

500

Unknown reason

Retrieving a User Account

You can get information to determine if a user account has been created for a specific username and to find out the role assigned to the user account.

Request

To retrieve a user account, use a GET request on the users endpoint:

GET /v1/users/username
Authorization: Bearer your-auth-token

Response

When successful, your response will be a HTTP status code 200 OK and a payload similar to the following:

{
   "users": [{
     "ROLES": "ROLE_ADMIN | ROLE_USER",
     "username": "username"
   }]
}

If not successful, the response may contain one of the following error codes:

HTTP Status CodeReason

401 Unauthorized

The Bearer token sent with the request is not valid. Verify that you are using a valid Bearer token and try again.

404 Not Found

A user account with the username submitted in the request was not found.

500

Unknown reason

Deleting a User Account

If an account is compromised or if there are any other reasons to delete it, the admin must delete the account. After you successfully delete an account, all the tokens associated with the account are removed from the system.

The admin account cannot be removed from the system.

Request

Use the following API call to delete a user account, where username is the name of the user account you want to delete. The Bearer token is the token belonging to the admin account.

DELETE /v1/users/username
Authorization: Bearer your-auth-token

Response

If successful, the user account is deleted. The response includes the HTTP status code 200 OK and the following payload:

{
   "users": [{
      "username": "username"
   }]
}

If not successful, the response may contain one of the following error codes:

HTTP Status CodeReason

400

Invalid username, admin

401

Unable to validate the credentials

403

Not using the admin account

404

Account does not exist

500

Unknown reason