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:

• Authentication
• Login Requests
• Login Responses
• Tokens

Authentication

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

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"}'

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

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:

• WhatsApp Enterprise Client Error Codes
• HTTP Status Codes

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.