/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.
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.
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" }
Name | Required | Description |
---|---|---|
| Yes | Must be a minimum of 4 characters and a maximum of 32 characters. |
| Yes | Must be a minimum of 8 characters and a maximum of 64 characters. |
| Yes | Authentication token for the administrator who is running the request. See Login and Authentication — Tokens documentation for more information. |
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 Code | Reason |
---|---|
|
Submit the request again with an appropriate length username/password. |
| You are not using the |
| 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:
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
.
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" }
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 Code | Reason |
---|---|
| Bad Request |
| Unable to validate the credentials |
| Account does not exist |
| Unknown reason |
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.
To retrieve a user account, use a GET
request on the users
endpoint:
GET /v1/users/username Authorization: Bearer your-auth-token
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 Code | Reason |
---|---|
| The |
| A user account with the username submitted in the request was not found. |
| Unknown reason |
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.
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
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 Code | Reason |
---|---|
| Invalid username, |
| Unable to validate the credentials |
| Not using the |
| Account does not exist |
| Unknown reason |