> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer tokens

> Learn the importance of using a different access token for the Customer Chat API. Explore the various customer authorization flows.

To authorize requests to the [Customer Chat API](/api/customer-chat/), you'll need a different access token than the one used for the [Agent Chat API](/api/agent-chat/) and [Configuration API](/api/configuration/).
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](#cookie-grant) if you want to receive an identity of a single customer or via [agent token grant](#agent-token-grant) in order to manage multiple customer identities.

## 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:

```url theme={null}
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 Text 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 the Text 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](#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.

```shell title="Cookie grant: new customer" theme={null}
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"
      }'
```

```json title="Sample response" theme={null}
{
  "access_token": "us-south1: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. If a customer's token has expired, use this same request — you don't need to create a new customer identity.

To achieve that, make the same exact same request as in [Case: New customer](#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](#case-new-customer).

```url theme={null}
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](/authentication/oauth-authorization/) 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 Text. An integration that follows this authorization flow acts as a middleman between an external system and Text, 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:

```url theme={null}
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](#case-new-customer-2)). Specify it if you want to [acquire a new token for an existing customer identity](#case-existing-customer-2). |
| `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 the Text 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](#case-existing-customer-2). |
| `token_type`      | Value: `Bearer`                                                                                                                                                                                                                           |
| `organization_id` | Organization ID for which the token is being issued                                                                                                                                                                                       |

```shell title="Agent token grant: new customer" theme={null}
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"
      }'
```

```json title="Sample response" theme={null}
{
  "access_token": "us-south1: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](#case-new-customer-2), but this time, specify `entity_id` to avoid creating a new identity. You can find your `entity_id` [in the response](#response-1) of the request to create a new customer identity.

```shell title="Agent token grant: existing customer" theme={null}
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"
      }'
```

```json title="Sample response" theme={null}
{
  "access_token": "us-south1: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:

```url theme={null}
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](/authentication/oauth-authorization#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. |

```shell title="Identity transfer: token generation" theme={null}
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"
}'
```

```json title="Sample response" theme={null}
{
  "identity_transfer_token": "us-south1: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:

```url theme={null}
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](/authentication/oauth-authorization/#pkce-extension). |

**Response**

The response is a JSON with the following parameters:

| Parameter      | Description                                                                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access_token` | A token you can use to call the Text 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](#case-existing-customer). |
| `token_type`   | Value: `Bearer`                                                                                                                                                                                                                       |

```shell title="Identity transfer: token exchange" theme={null}
curl "https://accounts.livechat.com/v2/customer/token" \
  -X POST \
  -d '{
    "grant_type": "identity_token",
    "client_id": "9cbf3a968289727cb3cdfe83ab1d9836",
    "code": "us-south1:test_SZhSSbShcZxrv580FA"
}'
```

```json title="Sample response" theme={null}
{
  "access_token": "us-south1: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](/api/customer-accounts/) 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](/api/customer-accounts/).

## Errors

If you get stuck or an error appears, see [API errors](/authentication/troubleshooting) or [Authorization errors](/authentication/errors).