API công khai phiên bản cũ - Living Security Platform

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 và Xác thực. 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.

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. ID bên phát hành không phải là ID khóa truy cập hay ID tổ chức.

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:

Đổ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.
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à:

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:

npm install @livingsecurity/sdk@^1

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

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:

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:

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

Khóa truy cập API

Tạo, xoay vòng và thu hồi thông tin xác thực API.

Tích hợp MCP

Kết nối các công cụ AI được hỗ trợ thông qua Model Context Protocol.

API công khai

Tài liệu tham khảo API công khai

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

​Máy chủ theo khu vực

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

​Xác thực

​SDK TypeScript

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

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

​Phân trang

​Lỗi

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

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

​Nhận trợ giúp

​Nội dung liên quan

Khóa truy cập API

Tích hợp MCP

Trước khi bắt đầu

Máy chủ theo khu vực

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

Xác thực

SDK TypeScript

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

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

Phân trang

Lỗi

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

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

Nhận trợ giúp

Nội dung liên quan