/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"}'
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.
Logging a user out via the users
endpoint will invalidate all of the auth tokens assigned to that account. Deleting a user will have the same effect, though that's much more drastic. Keep in mind that logging a user in via the users
endpoint will return a new auth token, but it will not invalidate auth tokens already in circulation for that user. Anyone in possession of a previously provisioned token will continue to be able to use it until it expires or is invalidated via one of the previously mentioned methods.