> For the complete documentation index, see [llms.txt](https://en.help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.help.firstline.cc/developer/api.md).

# API Documentation

{% hint style="success" %}

## **API and Webhook Integration Notice**

Integrating APIs and Webhooks must be performed by personnel with relevant backgrounds**engineers or technical staff to carry out the integration work**, the FIRST LINE customer service team**does not provide this type of technical support service**.

We recommend that you assess internal technical resources before proceeding. If you have further integration needs or require assistance, you may also refer to our**advanced paid technical support offerings**to obtain more comprehensive technical assistance and implementation recommendations.
{% endhint %}

## Obtain Token

Using the API requires token authentication, and each agent's token is independent and does not affect or invalidate others. The APIs a token can access follow the permissions of the employee data; for example, a token belonging to an employee with "agent" privileges will be unable to use many management-related APIs.

You can obtain it through the following two methods:

## <mark style="color:blue;">Get Token</mark>

<mark style="color:blue;">To use the API, authentication is required through a token. Each agent has an independent token, and they do not interfere with or invalidate each other. The scope of API access for a token is determined by the employee data permissions. For instance, a token with "agent" permissions will be unable to access various management-related APIs.</mark>

<mark style="color:blue;">It can be obtained through two methods:</mark>

### Obtain via the Employee interface in the system

After an administrator logs into FIRST LINE, go to the left menu "System" > "Employee", find the employee account that will use the API, click "Generate" and a permanent token will be created. If a new key is regenerated, the previous token belonging to that employee will immediately become invalid.&#x20;

### &#x20;<mark style="color:blue;">**Via the Employee Interface in the System**</mark>

<mark style="color:blue;">When an admin logs into FIRST LINE, navigate to the "System" > "Employee" option in the left menu. Locate the employee account for which you want to generate a token and click on "Generate." This action will create a permanent token. If a new key is generated, the old token belonging to that employee will immediately become invalid.</mark>

<figure><img src="https://3300265106-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNRu7dk70ei7JV9HlW9%2Fuploads%2F7CcR52Z5UkdGtmNh3kvJ%2Fimage.png?alt=media&amp;token=b24624b8-d39c-4385-948d-9e97d0c83e24" alt=""><figcaption></figcaption></figure>

### Obtain via API&#x20;

You can also generate a new token using the user's username and password. The usage is as follows: each time a new token is obtained, the old token will immediately become invalid. Depending on the usage scenario and security considerations, you only need to obtain it according to the configured cycle.

### <mark style="color:blue;">Get Token via API</mark>

<mark style="color:blue;">You can also generate a new token through the API using the user's username and password. The process is as follows: each time a new token is obtained, the old token will immediately become invalid. Depending on the usage scenario and security considerations, it is recommended to obtain a new token based on the configured period.</mark>

## Obtain Token

<mark style="color:green;">`POST`</mark> `https://{API_HOST}/api/v1/auth`

#### Path Parameters

| Name                                       | Type    | Description                                                                                       |
| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
| ttl                                        | integer | Key expiration time, in minutes. Default is 60 minutes. Enter 52560000 minutes for long-term use. |
| password<mark style="color:red;">\*</mark> | string  | user password                                                                                     |
| name<mark style="color:red;">\*</mark>     | string  | user account                                                                                      |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vYnNvLmxvY2FsaG9zdDo4MDAwL2FwaS92MS9hdXRoIiwiaWF0IjoxNTU0ODMxOTkyLCJleHAiOjE1NTUwNDgwNzksIm5iZiI6MTU1NDgzMjA3OSwianRpIjoiNzV2elE2cFVid2haTGU4UyIsInN1YiI6MSwicHJ2IjoiODdlMGFmMWVmOWZkMTU4MTJmZGVjOTcxNTNhMTRlMGIwNDc1NDZhYSIsImVtYWlsIjoib3JlaWxseS5zYWJyeW5hQGV4YW1wbGUub3JnIn0.-sQWox84CRUEtgTxKguPzDXe8kcZW4nArRDiveeiNt8",
    "token_type": "bearer",
    "expires_in": 216000
}
```

{% endtab %}
{% endtabs %}

## Refresh Token

<mark style="color:orange;">`PUT`</mark> `https://{API_HOST}/api/v1/auth`

#### Request Body

| Name     | Type   | Description                                             |
| -------- | ------ | ------------------------------------------------------- |
| name     | string | user account.                                           |
| password | string | user password.                                          |
| ttl      | number | Key expiration time, in minutes. Default is 60 minutes. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vYnNvLmxvY2FsaG9zdDo4MDAwL2FwaS92MS9hdXRoIiwiaWF0IjoxNTU0ODMxOTkyLCJleHAiOjE1NTUwNDgwNzksIm5iZiI6MTU1NDgzMjA3OSwianRpIjoiNzV2elE2cFVid2haTGU4UyIsInN1YiI6MSwicHJ2IjoiODdlMGFmMWVmOWZkMTU4MTJmZGVjOTcxNTNhMTRlMGIwNDc1NDZhYSIsImVtYWlsIjoib3JlaWxseS5zYWJyeW5hQGV4YW1wbGUub3JnIn0.-sQWox84CRUEtgTxKguPzDXe8kcZW4nArRDiveeiNt8",
    "token_type": "bearer",
    "expires_in": 216000
}
```

{% endtab %}
{% endtabs %}

```javascript
curl -X PUT
    -H "Content-Type: application/json:Authorization: Bearer eyJhbGciOiJIUzI1NiI..." https://{API_HOST}/api/v1/auth
```

## Revoke Token

<mark style="color:orange;">`PUT`</mark> `https://{API_HOST}/api/v1/auth/logout`

Revoke the currently used token, equivalent to logging this user out.

#### Request Body

| Name     | Type   | Description    |
| -------- | ------ | -------------- |
| name     | string | user account.  |
| password | string | user password. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
    "message": "Successfully logged out"
}
```

{% endtab %}
{% endtabs %}

```javascript
curl -X POST
    -H "Accept: application/json"
    -H "Content-Type: application/json:Authorization: Bearer eyJhbGciOiJIUzI1NiI..." https://{API_HOST}/api/v1/auth/logout
```

## Usage&#x20;

After obtaining the token, you can use that token to perform various API operations corresponding to the system permissions the account has. FIRST LINE's API requests can authenticate the token (access token) using one of the following two methods.

## <mark style="color:blue;">Usage</mark>

<mark style="color:blue;">After obtaining the token, you can perform various API operations corresponding to the system permissions associated with the account. FIRST LINE API requests can be authenticated using one of the following two methods with the access token.</mark>

### **Authorization header**&#x20;

`Authorization: Bearer eyJhbGciOiJIUzI1NiI...`

### **Query string parameter**&#x20;

`https://{API_HOST}/api/v1/some-what?token=eyJhbGciOiJIUzI1NiI...`

{% hint style="success" %}

### 🔗 Need an expert to provide API development and integration support?

We offer additional paid professional services to help you successfully integrate internal and external systems, including data flow integration for bot scripts. We are committed to refining API strategy deployment and data connections to ensure smooth system integration and provide the best user experience.

Our professional team will provide you with comprehensive support to ensure your needs are effectively addressed.
{% endhint %}