Customer Authorization
Introduction
To authorize requests to the Customer Chat API, you'll need a different access token than the one used for the Agent Chat API and Configuration API.
Throughout the whole API documentation, we'll refer to it as customer_access_token
.
Customer authorization flows allow you to receive an identity of a customer. You can do it via Cookie grant if you want to receive an identity of a single customer or via Agent token grant in order to manage multiple customer identities.
Postman collection
You can find all the requests from the Agent and Customer authorization flows in Postman. Remember to replace sample parameters with your own.
Cookie grant
Cookie grant is based on the __lc_cid
and __lc_cst
cookies, which store your customer identity data. These cookies are protected with the Secure
and HttpOnly
flags, which means that one can send the cookies only via HTTPS and only specific servers can access them.
The cookies are valid for 2 years, and each next call to https://accounts.livechat.com/v2/customer/token
extends their lifetime. The __lc_cid
and __lc_cst
cookies are necessary to recognize a customer when an access token is being issued.
This flow is recommended for frontend apps that support cookies, such as an app running in a web browser. Each app user has their own and unique customer identity.
Case: New customer
Use this variant to receive a new customer identity. To acquire an access token, make an HTTP POST request to the following URL:
https:/v2/customer/token
Request
Parameter | Required | Description |
---|---|---|
grant_type | yes | Use cookie for this authorization flow |
client_id | yes | Client ID of your application |
response_type | yes | Value: token |
organization_id | yes | Organization ID for which the token is being issued (required only if grant_type=cookie ) |
redirect_uri | no | One of the URLs defined in the Authorization block during app configuration. The LiveChat OAuth Server will redirect the user back to this URL after successful authorization. Required for grant_type=cookie , default: the value of the Origin header. |
Response
The response is a JSON with the following parameters:
Parameter | Description |
---|---|
access_token | A token you can use to call LiveChat APIs on behalf of the user (customer). |
entity_id | The ID of the newly created customer |
expires_in | A number in seconds specifying how long your customer access_token will be valid; 28800 sec by default. When it expires, you will need to generate a new access_token following Case: Existing customer). |
token_type | Value: Bearer |
organization_id | Organization ID for which the token is being issued |
The response also includes headers with the __lc_cid
and __lc_cst
cookies, for example:
Set-Cookie: __lc_cid=3aa138c1-c137-41c6-6b26-cface5857378; Path=/v2/customer; Domain=accounts.livechat.com; Expires=Sun, 18 Jun 2023 12:26:02 GMT; Max-Age=63072000; HttpOnly; Secure; SameSite=None
Set-Cookie: __lc_cst=87b9d0222e63e349da85535d07c81e1e1fb938de41f4e16e1d9ba5965f25db4aeea46b39d0fb; Path=/v2/customer; Domain=accounts.livechat.com; Expires=Sun, 18 Jun 2023 12:26:02 GMT; Max-Age=63072000; HttpOnly; Secure; SameSite=None
Your web browser will automatically store and attach these cookies to future requests when you try to acquire a new access token.
💡 Got stuck? See common Errors.
COOKIE GRANT: NEW CUSTOMER
curl "https://accounts.livechat.com/v2/customer/token" \
-X POST \
-d '{
"grant_type": "cookie",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"organization_id": "390e44e6-f1e6-0368c-z6ddb-74g14508c2ex",
"redirect_uri": "https://my-application.com"
}'
{
"access_token": "dal:test_SZhSSbShcZxrv580FA",
"entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
"expires_in": 28800,
"token_type": "Bearer",
"organization_id": "390e44e6-f1e6-0368c-z6ddb-74g14508c2ex"
}
Case: Existing customer
Use this option to generate a new access token for an already existing customer identity.
To achieve that, make the same exact same request as in Case: New customer.
Your entity_id
, or any other customer identity data, won't be overwritten. The web browser will attach cookies to the server allowing it to recognize you as an existing customer. You'll get a new access token, and cookies' lifetime will be extended, too. They will be valid for 2 years from your last request to https://accounts.livechat.com/v2/customer/token
.
Case: Separating customer identity between groups
Use this option to generate a new access token for a customer (existing or a new one), but with a separate identity per group. This requires the chat_between_groups
license property to be set to false
.
All other parameters in this request are the same as in Case: New customer.
https:/v2/customer/<organization_id>/<group_id>/token
Agent token grant
Agent token grant lets you create customer identity and use it to act on behalf of a customer. To begin, you'll need an agent access token with the customers:own
scope. You can get it via all of the Agent authorization flows except for Personal Access Tokens.
Agent token grant is recommended for backend integrations. It allows you to impersonate customers and simulate that they send messages from external systems, like Facebook Messenger or WhatsApp, in LiveChat. An integration that follows this authorization flow acts as a middleman between an external system and LiveChat, and it has the ability to manage multiple customer identities.
Case: New customer
First of all, make a HTTP POST request to create a new customer identity by calling the following URL:
https:/v2/customer/token
Remember to authorize your request using the Authorization
header with an agent access token.
Request
Parameter | Required | Description |
---|---|---|
grant_type | yes | Use agent_token (agent access token) for this authorization flow. |
client_id | yes | Client ID of your application |
response_type | yes | Value: token |
entity_id | no | Customer ID. If you don't specify it, a new customer identity will be created (Case: New customer). Specify it if you want to acquire a new token for an existing customer identity. |
organization_id | no | Organization ID for which the token is being issued (required only if grant_type=cookie ) |
Response
The response is a JSON with the following parameters:
Parameter | Description |
---|---|
access_token | A token you can use to call LiveChat APIs on behalf of the user (customer). |
client_id | Client Id of your app |
entity_id | The ID of the newly created customer |
expires_in | A number in seconds specifying how long your customer access_token will be valid; 28800 sec by default. When it expires, you will need to generate a new access_token following Case: Existing customer). |
token_type | Value: Bearer |
organization_id | Organization ID for which the token is being issued |
💡 Got stuck? See common Errors.
AGENT TOKEN GRANT: NEW CUSTOMER
curl "https://accounts.livechat.com/v2/customer/token" \
-H "Authorization: Bearer <access_token>" \
-X POST \
-d '{
"grant_type": "agent_token",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"response_type": "token"
}'
{
"access_token": "dal:test_SZhSSbShcZxrv580FA",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
"expires_in": 28800,
"token_type": "Bearer",
"organization_id": "390e44e6-f1e6-0368c-z6ddb-74g14508c2ex"
}
Case: Existing customer
Use this option to get a new access token for an already existing customer identity.
Make the same request as in Case: New customer, but this time, specify entity_id
to avoid creating a new identity. You can find your entity_id
in the response of the request to create a new customer identity.
AGENT TOKEN GRANT: EXISTING CUSTOMER
curl "https://accounts.livechat.com/v2/customer/token" \
-H "Authorization: Bearer <access_token>" \
-X POST \
-d '{
"grant_type": "agent_token",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"entity_id: "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
"response_type": "token"
}'
{
"access_token": "dal:test_SZhSSbShcZxrv580FB",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
"expires_in": 28800,
"token_type": "Bearer",
"organization_id": "390e44e6-f1e6-0368c-z6ddb-74g14508c2ex"
}
Identity token grant
Identity token grant lets you transfer a customer identity from one place to another, for example transfer the identity between devices or web browsers. To begin, you'll need a valid agent or customer access token.
Step 1: Generate an identity transfer token
First, you need to generate an identity transfer token by calling the following URL:
https:/v2/customer/identity_transfer
Remember to authorize your request using the Authorization
header with an agent access token or a customer access token.
Request
Parameter | Required | Description |
---|---|---|
bearer_type | yes | agent – when authorizing with an agent access token, customer – when authorizing with a customer access token. |
client_id | yes | Client ID of your application |
customer_id | no | Customer ID of the customer whose identity will be transferred; required when authorizing with an agent access token. |
code_challenge | no | Code challenge; as described in PKCE extension |
Response
The response is a JSON with the following parameters:
Parameter | Description |
---|---|
identity_transfer_token | A token you can use to transfer an identity; you can exchange it for a customer access token. |
expires_in | A number in seconds specifying how long your identity transfer token will be valid; 3600 sec by default. |
IDENTITY TRANSFER: TOKEN GENERATION
curl "https://accounts.livechat.com/v2/customer/identity_transfer" \
-H "Authorization: Bearer <access_token>" \
-X POST \
-d '{
"bearer_type": "agent",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"customer_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db"
}'
{
"identity_transfer_token": "dal:test_SZhSSbShcZxrv580FA",
"expires_in": 28800,
}
Step 2: Exchange the identity transfer token
After you've obtained an identity transfer token, you're able to exchange it for a customer access token using the identity_transfer grant type. To do so, call:
https:/v2/customer/token
No authorization is required for this call.
Request
Parameter | Required | Description |
---|---|---|
grant_type | yes | Use identity_token for this authorization flow. |
client_id | yes | Client ID of your application |
code | yes | identity transfer token |
code_verifier | no | Code verifier; as described in PKCE extension. |
Response
The response is a JSON with the following parameters:
Parameter | Description |
---|---|
access_token | A token you can use to call LiveChat APIs on behalf of the user (customer). |
client_id | Client Id of your app |
entity_id | The ID of the newly created customer |
expires_in | A number in seconds specifying how long your customer access_token will be valid; 28800 sec by default. When it expires, you'll need to generate a new access_token following Case: Existing customer). |
token_type | Value: Bearer |
IDENTITY TRANSFER: TOKEN EXCHANGE
curl "https://accounts.livechat.com/v2/customer/token" \
-X POST \
-d '{
"grant_type": "identity_token",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"code": "dal:test_SZhSSbShcZxrv580FA"
}'
{
"access_token": "dal:test_SZhSSbShcZxrv580FA",
"client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
"entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
"expires_in": 28800,
"token_type": "Bearer"
}
Revoking tokens
Look at the Customer Accounts API specification to find more details about revoking customer tokens.
Validating the access token
The instruction on how to validate customer access token of a customer is available in the Customer Accounts API specification.
Errors
If you get stuck or any error appears, please go to common Errors.