> 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 Guidelines**

Integration of API and Webhook must be carried out by**engineering or technical personnel**, the FIRST LINE customer service team**does not provide this type of technical support service**.

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

## Authentication Methods and Scope

General FIRST LINE API usage**Employee access token (Access Token)**, the data and functions available depend on that employee's permissions.**The Headless Conversation API uses a separate channel credential**, and cannot be mixed with employee access tokens.

### Method 1: Obtain a Token from the employee interface

An authorized administrator can find the corresponding employee in FIRST LINE "System → Employees" and generate a Token. If regenerated, please update the Token stored in the integration system at the same time to avoid the existing connection becoming invalid.

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

### Method 2: Obtain a Token by logging in via API

**POST** `https://{API_HOST}/api/v1/auth`

Use **JSON Request Body**, do not put the account or password in the URL.

| JSON field | Type    | Required | Description                                                                                                                   |
| ---------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `name`     | string  | Yes      | Employee login account                                                                                                        |
| `password` | string  | Yes      | Employee password                                                                                                             |
| `ttl`      | integer | No       | Validity period (minutes), default 60; whether longer durations are allowed depends on actual permissions and security policy |

```bash
curl -X POST "https://{API_HOST}/api/v1/auth" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"YOUR_EMPLOYEE_ACCOUNT","password":"YOUR_PASSWORD","ttl":60}'
```

The successful response will include the Access Token and related information; subsequent requests should use `Authorization: Bearer YOUR_ACCESS_TOKEN` as shown below.

### Update Token

**PUT** `https://{API_HOST}/api/v1/auth`

Use the currently valid Access Token to obtain a new Token,**you do not need to send the account or password again**.

```bash
curl -X PUT "https://{API_HOST}/api/v1/auth" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Upon success, a new `access_token`,`token_type`,`expires_in`, please update the Token stored by the integration side.

### Invalidate Token

**POST** `https://{API_HOST}/api/v1/auth/logout`

```bash
curl -X POST "https://{API_HOST}/api/v1/auth/logout" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Successful response:

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

### Call other APIs

```http
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json
```

`Content-Type` Used for requests with a JSON Request Body; requests without a body, such as GET, usually only need `Accept`. Please**Do not put the Access Token in URL parameters**(for example `?token=...`), to prevent the credential from appearing in URL logs.

{% hint style="warning" %}
Tokens should only be stored in a trusted backend environment. When a request occurs `401`,`403` , first check whether the credential is valid, whether the employee's permissions are sufficient, and whether the Token has been regenerated or revoked.
{% endhint %}

{% hint style="success" %}

### 🔗 Need expert help with API development and integration support?

We offer additional paid professional services to help you smoothly implement integrations between internal and external systems, including data flow integration such as bot scripts. We are committed to improving API strategy deployment and data integration 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 resolved.
{% endhint %}
