Users

/v1/users

Use the users node for managing authentication and accessing the WhatsApp Business API Client.

Edges

The following edges are connected to this node:

EdgeDescription

/login

Use this edge to login to the WhatsApp Business API client.

/logout

Use this edge to logout of the WhatsApp Business API client.

/{username}

Use this edge to retrieve or delete a user account.

Before You Start

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

The admin account is the only account that can create and delete users, so we recommend using the admin account only for this purpose. 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.

Example

To create a user, send a request like:

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

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

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

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

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

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

Parameters

NameDescription

username

Required.

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

Required.

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

Authorization

Required.

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

Common Errors

While creating a new user, you may encounter these 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: Error Codes and HTTP Status Codes.

All /users API Calls

NameActionReturns

POST /v1/users/login

Log in to get your authentication token

A users object containing the authentication token and the expiration date of the token

POST /v1/users

Send a username and password to create a user account

A users object containing the username sent in the request

GET /v1/users/username

Retrieve a user account

A users object containing the username sent in the request and that user's role

PUT /v1/users/username

Send a new password to update a user's password

A users object containing the username sent in the request

DELETE /v1/users/username

Delete a user account with the username sent in the request

A users object containing the username sent in the request

POST /v1/users/logout

Log out of a user account and delete the token associated with that account

No users (payload) object in response