/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.
To use the WhatsApp Business API, you must authenticate yourself. Only users with valid authentication tokens can access the service.
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).
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 Business Web 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.
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:
Password complexity is enforced upon creating a new account or changing an existing account's password.
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
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:
username:password 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.
When your login request is received by the WhatsApp Business API client, your credentials are processed for validation.
token field. 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"
}]
}
| Field | Required | Default Value/Description |
|---|---|---|
| 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: |
| Yes | Token expiration timestamp. By default, this is 7 days. |
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:
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.
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.
You can use your token for authentication until the token expires. A token can expire for these reasons:
expires_after parameter in the response provides the expiration date for the token. Log in again to generate a new token.Authentication tokens expire after 7 days, so you will need to log in weekly to update the Bearer token.