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

Copied!

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

Sample response

Copied!

{
  "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://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/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

Copied!

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

Sample response

Copied!

{
  "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

Copied!

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

Sample response

Copied!

{
  "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://accounts.livechatinc.com/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

Copied!

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

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:

https://accounts.livechatinc.com/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

Copied!

curl "https://accounts.livechat.com/v2/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.