> ## 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. # 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, xác thực bằng Basic auth và thực hiện yêu cầu đầu tiên tới Living Security Public 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](/vi/developers/v1/authentication) 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 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. 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. 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](/vi/developers/v1/regions) 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ủ. 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. ```bash cURL theme={null} 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" ``` ```bash cURL (key as username) theme={null} 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" ``` ```python Python theme={null} 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ị: ```json Response theme={null} { "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](/vi/developers/v1/regions). * **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](/vi/developers/developer-hub/api-keys) để 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](https://www.rfc-editor.org/rfc/rfc9457)) 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ề: ```json 401 Unauthorized theme={null} { "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](/vi/developers/v1/errors/overview). ## 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: ```bash cURL theme={null} 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](/vi/developers/v1/changelog). ## 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](/vi/developers/v1/changelog). | | `429 rate_limited` | Chờ `Retry-After`; làm theo [ví dụ thử lại có giới hạn](/vi/developers/v1/rate-limits). | | 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 Chọn máy chủ `/v1` US hoặc EU cho tổ chức. Duyệt danh sách bằng `page_token` và phong bì danh sách. Tìm hiểu về ngân sách yêu cầu và xử lý các phản hồi `429`. Mọi mã lỗi, trạng thái HTTP của mã đó và cách giải quyết. Quản lý tài khoản dịch vụ, khóa API và nhật ký yêu cầu. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.