On-Premises API

We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.

Users

/v1/users

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

Before You Start

The WhatsApp Business On-Premises API Client has a default account with admin set as the username with a password of secret. This account cannot be removed or deleted from the system. For security reasons, you are required to change the admin password immediately.

If you forget your password, please contact Direct Support for assistance with resetting it.

Limitations

  • Only the admin account can create or delete users.

Recommendations

  • Use the admin account only to create or delete users
  • Create user accounts to manage your WhatsApp Business On-Premises API Clients

Creating

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 On-Premises 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 between 8 and 64 characters and at least one character must be upper-case, lower-case, a digit, and a special character:


!\/'"#$%&()*+-.,:;_<>=?@[]{}^`|~

Authorization

Required.

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

Edges

The following edges are connected to this node:

EdgeDescription

/users/login

Use this edge to login to the WhatsApp Business On-Premises API Client.

/users/logout

Use this edge to logout of the WhatsApp Business On-Premises API Client.

/users/{username}

Use this edge to retrieve, update, or delete a user account.

Common 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.