Login and Authentication

/v1/users/login

To authenticate yourself with WhatsApp Business API client, you must log in. To log in, you send your username and password over basic authentication and receive a bearer token in response. You then use the bearer token for authentication when sending requests to any WhatsApp Business API endpoint.

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 on your first login.

Authentication

To use the WhatsApp Business API, you must authenticate yourself. Only users with valid authentication tokens can access the service.

Authentication Flow

Login Requests

You authenticate yourself using basic authentication (username, password) when you log in. The Authorization is set in the HTTP header. The type is Basic and the credentials are a base64-encoded string consisting of the username and password joined with a colon (i.e., username:password).

First Login

For security purposes, you are required to update the default admin password to a new password using the new_password field the first time you attempt to log in. If you try to log in with the default password and no new_password field information, the system will return an error.

Your first login should look like:

  POST /v1/users/login
  Authorization: Basic base64(username:password)
  {
  "new_password": "new-password"
  }

The cURL version should look like:

curl -k -X POST https://your-webapp-hostname:your-webapp-port/v1/users/login \
  -w "\n%{http-code}\n" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic base64(username:password)' \
  -d '{"new_password" : "new-password"}'

If you prefer not to use the WhatsApp Business API for the first login, you can use the WhatsApp Web Business Tool to change the password instead. Enter the default username and password into the login fields, and the system will automatically ask you to update the password.

Passwords

We recommended you use strong passwords when creating new accounts and when setting new accounts' passwords, as per industry best practices.

Passwords need to be between 8 and 64 characters long and have at least:

  • one digit
  • one uppercase character
  • one lowercase character
  • one special character from among !"#$%&\'()*+,-./:;<=>?@[]^_`{|}~

Password complexity is enforced upon creating a new account or changing an existing account's password.

Standard Login

After you have set a new password, you can use a standard login for the WhatsApp Business API client, which should look like:

POST /v1/users/login
Authorization: Basic base64(username:password)

The cURL version should look like:

curl -X POST \
  -H 'Authorization: Basic base64(username:password)' \
  -H 'Content-Type: application/json' \
  -d '{}' \
  https://your-webapp-hostname:your-webapp-port/v1/users/login

Authentication Header

Many client software apps (e.g., Postman) will take the username:password parameter and build the authentication header automatically. If you need to build it yourself, here are the basic steps:

  1. Create the username:password string.
  2. Use your favorite tool to base64-encode the string.

The base64 encoding for the default username and password string admin:secret results in YWRtaW46c2VjcmV0, so the admin credentials will be Authorization: Basic YWRtaW46c2VjcmV0.

Login Responses

When your login request is received by the WhatsApp Business API client, your credentials are processed for validation.

  • If successful, your token is generated. The response contains your token in the token field.
  • If not successful, an error is returned.

Success

On success, a status of 200 OK is returned, along with the token and token expiration time. All generated tokens expire in 7 days.

The response will look like the following example:

{
   "users": [{
      "token": "eyJhbGciOHlXVCJ9.eyJ1c2VyIjoNTIzMDE2Nn0.mEoF0COaO00Z1cANo",
      "expires_after": "2018-03-01 15:29:26+00:00"
   }]
}

Parameters

Field Required Default Value/Description

token

Yes

Authentication token to be used for all other WhatsApp Business API calls. The token must be sent in the authorization header in the format:
Authorization: Bearer <authentication-token>

expires_after

Yes

Token expiration timestamp. By default, this is 7 days.

Error

If the request is not successful, you will see an HTTP status of 401 Unauthorized. This error generally means that the username and/or password that was sent with the login request is invalid, and thus the WhatsApp Business API client is unable to generate the token.

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

Tokens

For your initial login, use your username and password for basic authentication. For all other secure interactions, you must use the bearer token that is returned after a successful login.

Usage

The tokens are sent in the authorization header of the HTTP request for many of the WhatsApp Business API calls. In particular, notice in the following example that the type of authorization that is used with this token is Bearer.

HTTP-METHOD /secured-path
Authorization: Bearer your-auth-token

For all secured paths, we validate the token. During validation, if a token is found to be expired, that token is removed from the system. Upon successful validation, the request is allowed to proceed. Requests made with an invalid token receive a 401 Unauthorized error code.

Expiration

You can use your token for authentication until the token expires. A token can expire for these reasons:

  • Periodic - Token are set to expire after a default time, such as 7 days. The expires_after parameter in the response provides the expiration date for the token. Log in again to generate a new token.
  • Explicit - Tokens are revoked when you log out, which is one way to explicitly revoke the token. If an user is removed from the system, then all associated tokens with that user are deleted.

Authentication tokens expire after 7 days, so you will need to log in weekly to update the Bearer token.