Hướng dẫn bắt đầu nhanh với API

Tạo tài khoản dịch vụ và khóa API trong Developer Hub, sau đó thực hiện yêu cầu đầu tiên của Quý vị. Hướng dẫn bắt đầu nhanh này sử dụng xác thực bằng khóa API; Quý vị không cần máy khách OAuth. Xem Xác thực nếu tích hợp của Quý vị yêu cầu mã truy cập OAuth có thời hạn ngắn.

Điều kiện tiên quyết

Quyền quản trị viên đối với Bảng điều khiển của Living Security.
Developer Hub hiển thị tại Cài đặt → Tích hợp & Nhà phát triển → Developer Hub.

Tạo thông tin xác thực

Tạo tài khoản dịch vụ

Trong Developer Hub, mở tab Tài khoản dịch vụ và tạo một tài khoản. Hãy đặt cho tài khoản một tên mô tả (ví dụ reporting-pipeline) và cấp các quyền mà các khóa của tài khoản được phép sử dụng — đối với hướng dẫn này, organization:read là đủ.Các quyền của tài khoản là giới hạn tối đa cho mọi khóa được tạo dưới tài khoản đó: một khóa không bao giờ có thể làm nhiều hơn những gì tài khoản dịch vụ của nó cho phép.

Tạo khóa API

Mở trang chi tiết của tài khoản dịch vụ và tạo một khóa. Chọn các quyền mà khóa cụ thể này cần (một tập con của các quyền của tài khoản) và thời hạn hết hạn — 30, 90 hoặc 365 ngày, hoặc một khoảng thời gian tùy chỉnh. Thời hạn hết hạn là bắt buộc.Chuỗi bí mật của khóa bắt đầu bằng lsk_live_ và chỉ hiển thị một lần. Hãy sao chép ngay vào trình quản lý bí mật; không thể truy xuất lại sau đó.

Không bao giờ commit chuỗi bí mật của khóa API vào hệ thống quản lý phiên bản hoặc nhúng chúng vào mã phía máy khách. Bất kỳ ai nắm giữ chuỗi bí mật đều có thể hành động với các quyền của khóa.

Chọn khu vực của Quý vị

Gọi đến máy chủ /v1 theo khu vực phù hợp với nơi lưu trữ dữ liệu của tổ chức. Khóa chỉ xác thực được trên máy chủ đó.

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

Xem Khu vực nếu Quý vị không chắc nên sử dụng máy chủ nào. Một khóa hợp lệ được gửi đến khu vực còn lại sẽ thất bại với lỗi unauthorized. Sử dụng danh sách thả xuống khu vực trên mẫu bên dưới để chuyển đổi máy chủ.

Thực hiện yêu cầu đầu tiên

Nạp LIVING_SECURITY_API_KEY từ trình quản lý bí mật vào môi trường của tiến trình thực hiện yêu cầu. Các ví dụ bên dưới đọc giá trị này mà không nhúng chuỗi bí mật vào mã nguồn. Đối với Python, hãy cài đặt requests trước.Gọi API với chuỗi bí mật đặt trong trường mật khẩu hoặc trường tên người dùng của HTTP Basic auth — cách nào cũng được, do đó các máy khách yêu cầu điền cả hai trường (chẳng hạn trình kết nối Web của Power BI) có thể đặt một giá trị giữ chỗ như apikey vào trường còn lại.

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}:" \
  -H "Living-Security-Version: 2026-07-01"

import os
import requests

BASE = "https://api.eu-west-1.livingsecurity.ai/v1"

response = requests.get(
    f"{BASE}/organization",
    auth=("apikey", os.environ["LIVING_SECURITY_API_KEY"]),
    headers={"Living-Security-Version": "2026-07-01"},
    timeout=(5, 30),
    allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 200:
    raise RuntimeError("Unexpected response; check your regional API URL")
print(response.json())

Phản hồi thành công sẽ trả về tổ chức của Quý vị:

Response

{
  "id": "1e2f3a4b-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
  "object": "organization",
  "name": "Example Corp",
  "region": "eu",
  "plan": "enterprise",
  "subscription_status": "active",
  "created_at": "2024-03-12T18:04:11.000Z"
}

Nếu nhận được phản hồi này, thông tin xác thực của Quý vị hoạt động. Yêu cầu cũng sẽ xuất hiện trong tab Nhật ký yêu cầu của Developer Hub trong giây lát.

Xác thực Bearer với cùng chuỗi bí mật (Authorization: Bearer lsk_live_...) cũng hoạt động. Basic auth tồn tại để các công cụ chỉ hỗ trợ tên người dùng/mật khẩu — như trình kết nối Web của Power BI — có thể kết nối.

Cách xác thực hoạt động

Thông tin xác thực quyết định tổ chức. Các yêu cầu /v1 không mang bộ chọn tenant nào: không có phân đoạn đường dẫn tổ chức và không có tiêu đề tổ chức. Việc gửi tiêu đề x-organization-id sẽ bị từ chối với invalid_request. Máy chủ vẫn phải khớp với khu vực của tổ chức đó. Xem Khu vực.
Quyền được kiểm tra theo từng thao tác. Mỗi thao tác /v1 yêu cầu một quyền được đặt tên (ví dụ, GET /v1/organization yêu cầu organization:read). Khóa thiếu quyền sẽ nhận được 403 với mã insufficient_permission.
Khóa hết hạn và có thể được luân chuyển mà không gây gián đoạn. Xem Khóa API để biết cách luân chuyển với khoảng thời gian chồng lấp.

Đọc phản hồi lỗi

Mọi lỗi /v1 đều là application/problem+json (RFC 9457) với một mã máy ổn định. Ví dụ, một yêu cầu thiếu thông tin xác thực hoặc có thông tin xác thực không xác định sẽ trả về:

401 Unauthorized

{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API credential was provided.",
  "code": "unauthorized",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/unauthorized",
  "retryable": false
}

Hãy phân nhánh xử lý dựa trên code, không bao giờ dựa trên detail. Làm theo doc_url để biết các bước giải quyết, và cung cấp request_id khi liên hệ bộ phận hỗ trợ — giá trị này khớp với tiêu đề phản hồi Request-Id và nhật ký yêu cầu của Developer Hub. Toàn bộ tập mã lỗi có trong tài liệu tham chiếu lỗi.

Phiên bản hợp đồng

Mỗi phản hồi phản ánh lại phiên bản hợp đồng đã xử lý nó trong tiêu đề Living-Security-Version, cùng với tiêu đề Request-Id để đối chiếu. Quý vị có thể ghim một yêu cầu vào một phiên bản hợp đồng đã phát hành theo ngày:

curl --fail-with-body --connect-timeout 5 --max-time 30 \
  https://api.eu-west-1.livingsecurity.ai/v1/organization \
  -u "apikey:${LIVING_SECURITY_API_KEY:?Set LIVING_SECURITY_API_KEY}" \
  -H "Living-Security-Version: 2026-07-01"

Phiên bản được xác định theo thứ tự sau: tiêu đề yêu cầu nếu có, nếu không thì phiên bản mặc định được ghim của tài khoản dịch vụ, nếu không thì phiên bản mới nhất đã phát hành. Việc yêu cầu một phiên bản chưa được phát hành (hoặc đã quá ngày ngừng hỗ trợ) sẽ trả về 400 với mã unsupported_version. Các phiên bản đã phát hành và những thay đổi của chúng được liệt kê trong nhật ký thay đổi API.

Khắc phục sự cố yêu cầu đầu tiên

Kết quả	Hành động tiếp theo
`401 unauthorized`	Kiểm tra chuỗi bí mật, thời hạn hết hạn và khu vực của tổ chức. Không thử các máy chủ khác bằng thông tin xác thực đang hoạt động.
`403 insufficient_permission`	Cấp `organization:read` cho cả tài khoản dịch vụ và khóa của tài khoản đó.
`400 unsupported_version`	Chọn một phiên bản đã phát hành từ nhật ký thay đổi.
`429 rate_limited`	Chờ `Retry-After`; làm theo ví dụ thử lại có giới hạn.
Hết thời gian chờ mạng	Kiểm tra kết nối và thử lại yêu cầu đọc này trong phạm vi ngân sách thử lại của ứng dụng.

Đối với các lỗi khác, hãy làm theo doc_url của phản hồi. Hãy giữ lại Request-Id để cung cấp cho bộ phận hỗ trợ; không bao giờ đưa tiêu đề Authorization hoặc khóa API của Quý vị vào phiếu hỗ trợ.

Các bước tiếp theo

Khu vực

Chọn máy chủ /v1 US hoặc EU cho tổ chức.

Phân trang

Duyệt danh sách bằng page_token và phong bì danh sách.

Giới hạn tốc độ

Tìm hiểu về ngân sách yêu cầu và xử lý các phản hồi 429.

Tài liệu tham chiếu lỗi

Mọi mã lỗi, trạng thái HTTP của mã đó và cách giải quyết.

Developer Hub

Quản lý tài khoản dịch vụ, khóa API và nhật ký yêu cầu.

Trung tâm nhà phát triển

API công khai v1

Tài liệu tham khảo API v1

Hướng dẫn bắt đầu nhanh với API

Điều kiện tiên quyết

Tạo thông tin xác thực

Cách xác thực hoạt động

Đọc phản hồi lỗi

Phiên bản hợp đồng

Khắc phục sự cố yêu cầu đầu tiên

Các bước tiếp theo

Khu vực

Phân trang

Giới hạn tốc độ

Tài liệu tham chiếu lỗi

Developer Hub

Trung tâm nhà phát triển

API công khai v1

Tài liệu tham khảo API v1

​Điều kiện tiên quyết

​Tạo thông tin xác thực

​Cách xác thực hoạt động

​Đọc phản hồi lỗi

​Phiên bản hợp đồng

​Khắc phục sự cố yêu cầu đầu tiên

​Các bước tiếp theo

Khu vực

Phân trang

Giới hạn tốc độ

Tài liệu tham chiếu lỗi

Developer Hub

Điều kiện tiên quyết

Tạo thông tin xác thực

Cách xác thực hoạt động

Đọc phản hồi lỗi

Phiên bản hợp đồng

Khắc phục sự cố yêu cầu đầu tiên

Các bước tiếp theo