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

# API công khai phiên bản cũ

> Duy trì các tích hợp /api/v1 hiện có sử dụng khóa truy cập API để đổi lấy bearer token.

Hướng dẫn này đề cập đến các tích hợp `/api/v1` hiện có sử dụng khóa truy cập API để đổi lấy bearer token. Thông tin xác thực và định dạng yêu cầu của các tích hợp này khác với API công khai `/v1`.

Đối với tích hợp mới, hãy bắt đầu với [Hướng dẫn nhanh về API](/vi/developers/v1/quickstart) và [Xác thực](/vi/developers/v1/authentication). API `/v1` mới sử dụng khóa API của tài khoản dịch vụ hoặc access token OAuth.

## Trước khi bắt đầu

Bạn cần có:

* Quyền truy cập Living Security cho phép quản lý khóa truy cập API
* Một khóa truy cập API được tạo tại **Cài đặt → Access Keys**
* Khóa bí mật của khóa truy cập chỉ hiển thị một lần khi thông tin xác thực được tạo
* ID bên phát hành API (API issuer ID) do Living Security cung cấp cùng với thông tin xác thực API công khai của bạn
* URL cơ sở theo khu vực của tổ chức mà bạn đang tích hợp
* Môi trường chạy phía máy chủ và một trình quản lý khóa bí mật

Không được đặt khóa bí mật của khóa truy cập trong mã trình duyệt, ứng dụng di động, hệ thống quản lý mã nguồn, biến môi trường phía máy khách, phiếu yêu cầu hoặc nhật ký dùng chung.

<Note>
  Hộp thoại Access Keys hiển thị khóa bí mật chỉ xuất hiện một lần, nhưng không hiển thị ID bên phát hành API. Nếu Living Security chưa cung cấp ID bên phát hành cùng với thông tin xác thực API công khai của bạn, hãy yêu cầu ID này từ [Bộ phận Hỗ trợ của Living Security](mailto:support@livingsecurity.com). ID bên phát hành không phải là ID khóa truy cập hay ID tổ chức.
</Note>

## Máy chủ theo khu vực

Hợp đồng API phiên bản cũ sử dụng các máy chủ production `/api/v1` theo khu vực sau:

| Khu vực | URL cơ sở |
| - | - |
| US | `https://api.us-east-1.livingsecurity.ai/api/v1` |
| EU | `https://api.eu-west-1.livingsecurity.ai/api/v1` |

Hãy sử dụng khu vực được chỉ định cho tổ chức Living Security. Không chuyển đổi khu vực để khắc phục lỗi ủy quyền hoặc lỗi khả dụng.

## Tài nguyên phiên bản cũ

| Tài nguyên | Thao tác được hỗ trợ |
| - | - |
| **Mọi người** | Tìm kiếm người trong tổ chức và truy xuất tư cách thành viên của một người |
| **Khóa truy cập API** | Tạo, liệt kê, xoay vòng và thu hồi khóa truy cập API |

Hãy sử dụng **Developers → Public API Reference** để xem danh sách đầy đủ về thao tác, tham số, yêu cầu, phản hồi và lược đồ. Nếu một thao tác không có ở đó, thao tác đó hiện không thuộc API công khai.

## Xác thực

Quyền truy cập API công khai gồm hai giai đoạn:

1. Đổi khóa truy cập bí mật và ID bên phát hành API lấy một bearer token có thời hạn ngắn và ID tổ chức.
2. Gửi bearer token và ID tổ chức kèm theo mỗi yêu cầu API.

Các header yêu cầu bắt buộc là:

```http theme={null}
Authorization: Bearer <access-token>
x-organization-id: <organization-id>
```

Header tổ chức phải là tổ chức được trả về từ bước đổi khóa truy cập. Một khóa không cấp quyền truy cập vào một ID tổ chức tùy ý.

### SDK TypeScript

Cài đặt phiên bản chính hiện tại:

```bash theme={null}
npm install @livingsecurity/sdk@^1
```

Sau đó đổi khóa và cấu hình SDK:

```typescript theme={null}
import { configure, exchangeAccessKey } from "@livingsecurity/sdk";

const accessKeySecret = process.env.LS_API_ACCESS_KEY_SECRET;
const apiIssuerId = process.env.LS_API_ISSUER_ID;

if (!accessKeySecret || !apiIssuerId) {
  throw new Error("LS_API_ACCESS_KEY_SECRET and LS_API_ISSUER_ID are required");
}

const { accessToken, organizationId } = await exchangeAccessKey(
  accessKeySecret,
  apiIssuerId,
);

configure({
  baseUrl: "https://api.us-east-1.livingsecurity.ai/api/v1",
  accessToken,
  organizationId,
});
```

Hãy sử dụng URL cơ sở EU cho tổ chức thuộc khu vực EU. Việc đổi khóa bằng SDK được thiết kế cho môi trường chạy Node.js phía máy chủ.

### Yêu cầu REST trực tiếp

Nếu bạn thực hiện bước đổi khóa bên ngoài SDK, hãy gửi bearer token và ID tổ chức của bước đó trong mọi yêu cầu:

```bash theme={null}
curl --request GET \
  "https://api.us-east-1.livingsecurity.ai/api/v1/people/search?limit=1" \
  --header "Authorization: Bearer $LIVING_SECURITY_BEARER_TOKEN" \
  --header "x-organization-id: $LIVING_SECURITY_ORG_ID" \
  --header "Accept: application/json"
```

Bearer token có thời hạn ngắn. Hãy đổi lại khóa truy cập khi cần lấy token mới, thay vì lưu bearer token như một thông tin xác thực vĩnh viễn.

## Vòng đời của khóa truy cập

* Đặt tên khóa theo tích hợp hoặc quy trình tự động hóa sở hữu khóa đó.
* Chọn các phạm vi quyền tối thiểu được cung cấp trong biểu mẫu khóa truy cập.
* Lưu khóa bí mật chỉ hiển thị một lần ngay lập tức; không thể truy xuất lại sau khi tạo hoặc xoay vòng.
* Xoay vòng khóa tại **Cài đặt → Access Keys** và triển khai khóa thay thế trước khi thu hồi thông tin xác thực cũ.
* Thu hồi các khóa không còn được sử dụng hoặc có khóa bí mật có thể đã bị lộ.
* Sử dụng khóa tài khoản dịch vụ cho các tích hợp không do con người vận hành khi loại khóa đó khả dụng đối với tổ chức của bạn.

## Phân trang

Tìm kiếm người hỗ trợ các tham số `limit`, `cursor`, `offset` và `includeTotal`. Nên ưu tiên sử dụng con trỏ được trả về từ phản hồi trước đó để duyệt tuần tự.

* `limit` mặc định là 50 và chấp nhận giá trị từ 1–100.
* `cursor` tiếp tục từ một phản hồi trước đó.
* `offset` bỏ qua một số lượng bản ghi và mặc định là 0.
* `includeTotal=true` yêu cầu số đếm chính xác sau khi lọc; hãy bỏ qua tham số này khi không cần số đếm.

Hãy đọc đối tượng `pagination` do endpoint trả về. Không tự tính trang tiếp theo dựa trên số hàng nhận được, và không kết hợp các yêu cầu được phân trang độc lập rồi tự sắp xếp các kết quả một phần.

## Lỗi

Các lỗi JSON được ghi nhận trong tài liệu có cấu trúc chung như sau:

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```

`message` có thể là một chuỗi hoặc một mảng các thông báo xác thực.

| Trạng thái | Ý nghĩa | Cách xử lý |
| - | - | - |
| `400` | Tham số hoặc nội dung yêu cầu không hợp lệ | Sửa các lỗi xác thực được nêu |
| `401` | Bearer token bị thiếu, không hợp lệ hoặc đã hết hạn | Đổi lại khóa truy cập và thử lại một lần |
| `403` | Thông tin xác thực thiếu quyền hoặc quyền truy cập tổ chức | Kiểm tra phạm vi quyền của khóa và ngữ cảnh tổ chức |
| `404` | Tài nguyên không tồn tại trong tổ chức được ủy quyền | Xác minh ID tài nguyên và tổ chức |
| `408` | Yêu cầu bị hết thời gian chờ | Thử lại với cơ chế exponential backoff có giới hạn |
| `429` | Đã đạt giới hạn tốc độ | Chờ ít nhất bằng khoảng thời gian của `Retry-After`, khi có |
| `5xx` | Lỗi dịch vụ tạm thời | Thử lại các thao tác đọc an toàn với exponential backoff có giới hạn |

Hợp đồng được biên soạn hiện không công bố một giới hạn tốc độ bằng số chung cho mọi trường hợp, cũng không đảm bảo có header phản hồi chứa ID yêu cầu cho mọi thao tác. Hãy ghi lại thời gian UTC, phương thức, đường dẫn, trạng thái và nội dung phản hồi đã được làm sạch khi yêu cầu hỗ trợ.

Không tự động thử lại các thao tác tạo, xoay vòng, thu hồi hoặc xóa, trừ khi thao tác đó ghi rõ tính idempotent. Hãy kiểm tra trạng thái tài nguyên hiện tại sau khi xảy ra lỗi mạng không rõ kết quả.

## Tính tương thích và ngừng hỗ trợ

V1 mặc định phát triển theo hướng bổ sung. Máy khách phải bỏ qua các trường phản hồi không xác định. Một thay đổi gây phá vỡ yêu cầu có lộ trình di chuyển được ghi nhận trong tài liệu; các thao tác bị ngừng hỗ trợ vẫn được giữ trong tài liệu tham chiếu kèm lý do, giải pháp thay thế (nếu có) và ngày ngừng hoạt động trong giai đoạn di chuyển.

Hãy cố định SDK ở một phiên bản chính tương thích và xem ghi chú phát hành trước khi nâng cấp. Hãy coi Public API Reference được tạo tự động, chứ không phải các ứng dụng máy khách của bên thứ nhất, là nguồn tham chiếu chuẩn về lược đồ.

## API công khai, MCP và ứng dụng web

| Bề mặt | Dùng cho | Mô hình tương thích |
| - | - | - |
| **API công khai** | Hệ thống của khách hàng, đối tác và tự động hóa bên ngoài | Tài nguyên ổn định, có phiên bản |
| **MCP** | Tương tác với công cụ AI có phân quyền | Hợp đồng công cụ và đầu ra có cấu trúc gọn |
| **Ứng dụng web** | Quy trình của con người trong sản phẩm Living Security | Hợp đồng do ứng dụng sở hữu, có thể thay đổi cùng giao diện |

Xem [Tích hợp MCP](/vi/integrations/mcp) để kết nối công cụ AI với Living Security.

## Nhận trợ giúp

Liên hệ [Bộ phận Hỗ trợ của Living Security](mailto:support@livingsecurity.com) kèm theo:

* Tổ chức và khu vực
* Tên và phiên bản SDK, nếu có sử dụng
* Dấu thời gian UTC, phương thức và đường dẫn
* Trạng thái HTTP và nội dung lỗi đã được làm sạch

Tuyệt đối không đưa vào khóa bí mật của khóa truy cập, bearer token hoặc dữ liệu riêng tư của khách hàng.

## Nội dung liên quan

<CardGroup cols={2}>
  <Card title="Khóa truy cập API" icon="key" href="/vi/integrations/api-keys">
    Tạo, xoay vòng và thu hồi thông tin xác thực API.
  </Card>

  <Card title="Tích hợp MCP" icon="robot" href="/vi/integrations/mcp">
    Kết nối các công cụ AI được hỗ trợ thông qua Model Context Protocol.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.