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.

Run in Postman

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/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://accounts.livechat.com/customer/token
Request
ParameterRequiredDescription
grant_typeyesUse cookie for this authorization flow
client_idyesClient ID of your application
license_idyesLicense ID for which the token is being issued
redirect_urinoThe LiveChat OAuth Server will redirect the user back to this URI after successful authorization. Possible values: the Origin header (default) or one of the URIs defined in the App Authorization block in Developer Console. The param is required if you defined a URI in the Console.
Response

The response is a JSON with the following parameters:

ParameterDescription
access_tokenA token you can use to call LiveChat APIs on behalf of the user (customer).
client_idClient Id of your app
entity_idThe ID of the newly created customer
expires_inA number in seconds specifying how long you customer access_token will be valid; 28800 sec by default. When it expires, you will need to generate new access_token following Case: Existing customer).
token_typeValue: Bearer

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=/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=/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
Copied!
curl "https://accounts.livechat.com/customer/token" \
  -X POST \
  -d '{
    "grant_type": "cookie",
    "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
    "license_id": 2491303,
    "redirect_uri": "https://my-application.com"
      }'
Sample response
Copied!
{
  "access_token": "dal:test_SZhSSbShcZxrv580FA",
  "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
  "entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
  "expires_in": 28800,
  "token_type": "Bearer"
}

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' 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/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://accounts.livechat.com/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://accounts.livechat.com/customer/token

Remember to authorize your request using the Authorization header with an agent access token.

Request
ParameterRequiredDescription
grant_typeyesUse agent_token for this authorization flow.
client_idyesClient ID of your application
entity_idnoCustomer ID. If you don't specify it, new customer identity will be created. Specify it if you want to acquire a new token for an existing customer identity.
Response

The response is a JSON with the following parameters:

ParameterDescription
access_tokenA token you can use to call LiveChat APIs on behalf of the user (customer).
client_idClient Id of your app
entity_idThe ID of the newly created customer
expires_inA 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 new access_token following Case: Existing customer).
token_typeValue: Bearer

💡 Got stuck? See common Errors.

AGENT TOKEN GRANT: NEW CUSTOMER
Copied!
curl "https://accounts.livechat.com/customer/token" \
  -H "Authorization: Bearer <access_token>" \
  -X POST \
  -d '{
    "grant_type": "agent_token",
    "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
    "response_type": "token"
      }'
Sample response
Copied!
{
  "access_token": "dal:test_SZhSSbShcZxrv580FA",
  "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
  "entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
  "expires_in": 28800,
  "token_type": "Bearer"
}

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
Copied!
curl "https://accounts.livechat.com/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"
      }'
Sample response
Copied!
{
  "access_token": "dal:test_SZhSSbShcZxrv580FB",
  "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
  "entity_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db",
  "expires_in": 28800,
  "token_type": "Bearer"
}

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:

/customer/identity_transfer
Copied!
https://accounts.livechatinc.com/customer/identity_transfer

Remember to authorize your request using the Authorization header with an agent access token or a customer access token.

Request
ParameterRequiredDescription
bearer_typeyesagent – when authorizing with an agent access token, customer – when authorizing with a customer access token.
client_idyesClient ID of your application
customer_idnoCustomer ID of the customer whose identity will be transferred; required when authorizing with an agent access token.
code_challengenoCode challenge; as described in PKCE extension
Response

The response is a JSON with the following parameters:

ParameterDescription
identity_transfer_tokenA token you can use to transfer an identity; you can exchange it for a customer access token.
expires_inA number in seconds specifying how long your identity transfer token will be valid; 3600 sec by default.
IDENTITY TRANSFER: TOKEN GENERATION
Copied!
curl "https://accounts.livechat.com/customer/identity_transfer" \
  -H "Authorization: Bearer <access_token>" \
  -X POST \
  -d '{
    "bearer_type": "agent",
    "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
    "customer_id": "bf18d1a8-1afe-4a3e-4cc0-a3148f1143db"
}'
Sample response
Copied!
{
  "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:

/customer/token
Copied!
https://accounts.livechatinc.com/customer/token

No authorization is required for this call.

Request
ParameterRequiredDescription
grant_typeyesUse identity_token for this authorization flow.
client_idyesClient ID of your application
codeyesidentity transfer token
code_verifiernoCode verifier; as described in PKCE extension.
Response

The response is a JSON with the following parameters:

ParameterDescription
access_tokenA token you can use to call LiveChat APIs on behalf of the user (customer).
client_idClient Id of your app
entity_idThe ID of the newly created customer
expires_inA number in seconds specifying how long you 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_typeValue: Bearer
IDENTITY TRANSFER: TOKEN EXCHANGE
Copied!
curl "https://accounts.livechat.com/customer/token" \
  -X POST \
  -d '{
    "grant_type": "identity_token",
    "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
    "code": "dal:test_SZhSSbShcZxrv580FA"
}'
Sample response
Copied!
{
  "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.

...

Join the community
Get in direct contact with us through Discord.
Follow us
Follow our insightful tweets and interact with out content.
Contribute
See something that's wrong or unclear? Submit a pull request.
Contact us
Want to share feedback? Reach us at: developers@livechat.com