Khóa API và phạm vi quyền

Mọi yêu cầu tới Sursa API đều được thực hiện bằng khóa API của tổ chức bạn. Khóa thuộc về tổ chức, không thuộc về một người: nó vẫn hoạt động khi nhân viên đã tạo nó rời đi, và những gì nó được làm được thiết lập ngay trên khóa.

Khóa được phép làm gì

Ba thiết lập của khóa quyết định yêu cầu dùng khóa đó được xem và thay đổi những gì. Mỗi thiết lập chỉ thu hẹp thêm các thiết lập còn lại.

Thiết lập	Kiểm soát điều gì
Vai trò	`admin`, `editor`, `verifier` hoặc `viewer`, cũng là các vai trò mà người dùng có. Khóa làm được những gì người dùng có vai trò đó làm được.
Phạm vi quyền	Những phần nào của API mà khóa được gọi, ví dụ `cards:read` hoặc `webhooks:manage`. Xem Phạm vi quyền của khóa.
Hồ sơ dữ liệu	Không bắt buộc. Giới hạn khóa trong các danh mục tri thức mà hồ sơ cho phép, giống như người dùng có hồ sơ đó.

Khóa cũng có thể được giới hạn trong một số bộ sưu tập và được đặt ngày hết hạn. Yêu cầu nằm ngoài các giới hạn này sẽ thất bại: thiếu phạm vi quyền trả về 403 với mã api_keys.scope, còn đối tượng mà khóa không được xem trả về 404, đúng như thể nó không tồn tại.

Hãy cấp cho mỗi tích hợp một khóa riêng với vai trò và phạm vi quyền hẹp nhất mà nó cần. Tác vụ đồng bộ chỉ ghi tài liệu không cần admin; tác vụ báo cáo không cần phạm vi ghi.

Tạo khóa

Quản trị viên của tổ chức tạo khóa trong Sursa tại Administration → API keys (Quản trị → Khóa API), hoặc bằng POST /v1/api-keys với một khóa hoặc phiên có vai trò admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Phản hồi chứa giá trị khóa trong key. Giá trị này chỉ hiển thị một lần: Sursa chỉ giữ giá trị băm của nó và không thể hiển thị lại. Khóa có dạng kb_ theo sau là 43 ký tự; các ký tự đầu (prefix) được hiển thị trong danh sách khóa để bạn phân biệt các khóa với nhau.

Khi không có scopes, khóa nhận các phạm vi quyền của vai trò. Truyền scopes để thu hẹp thêm. Khi không có expires_at, khóa không hết hạn.

Giữ bí mật khóa

Lưu khóa trong trình quản lý bí mật hoặc trong biến môi trường của dịch vụ, không bao giờ trong mã nguồn.
Chỉ dùng khóa từ máy chủ của bạn. Sursa chấp nhận yêu cầu từ trình duyệt (CORS mở), nhưng khóa trong trang web hiển thị với mọi người mở trang đó.
Không bao giờ gửi khóa trong URL. Chỉ gửi nó trong header Authorization.
Nếu khóa bị lộ, hãy thu hồi ngay và tạo khóa mới.

Kiểm tra khóa

GET /v1/me trả về khóa, vai trò, các phạm vi quyền thực tế, hồ sơ dữ liệu, ngày hết hạn và giới hạn tốc độ của nó. Endpoint này hoạt động với mọi khóa hợp lệ, bất kể phạm vi quyền, nên hãy dùng nó để kiểm tra kết nối của tích hợp và khi tìm hiểu nguyên nhân của một lỗi 403.

Xoay vòng khóa

Xoay vòng thay thế một khóa mà không dừng tích hợp. Cách nhanh nhất là cấp lại khóa: POST /v1/api-keys/{key_id}/roll cấp một giá trị mới cho cùng khóa đó, với cùng vai trò, phạm vi quyền, bộ sưu tập và ngày hết hạn. Giá trị trước đó vẫn hoạt động trong overlap_hours (mặc định 24 giờ, tối đa 168), nên bạn có thể triển khai giá trị mới trong thời gian đó; POST /v1/api-keys/{key_id}/revoke-previous kết thúc sớm thời gian chồng lấn.

Còn để thay khóa bằng một khóa khác:

Tạo khóa mới với cùng vai trò, phạm vi quyền và hồ sơ dữ liệu.
Triển khai khóa mới cho tích hợp của bạn.
Theo dõi khóa cũ tại Administration → API keys (hoặc last_used trong GET /v1/api-keys) cho tới khi nó không còn được dùng.
Thu hồi khóa cũ.

Hãy đặt ngày hết hạn cho khóa và xoay vòng chúng trước ngày đó. Sursa cảnh báo các quản trị viên của tổ chức trước khi khóa hết hạn; khóa đã hết hạn trả về 401 với mã api_keys.expired.

Thu hồi khóa

Thu hồi khóa tại Administration → API keys hoặc bằng DELETE /v1/api-keys/{key_id}. Việc thu hồi có hiệu lực trong vài giây trên mọi máy chủ API. Yêu cầu với khóa đã bị thu hồi trả về 401 với mã auth.not_authenticated.

Khóa của nguồn tùy chỉnh

Nguồn tùy chỉnh có loại khóa riêng. Khóa này bắt đầu bằng kbsrc_, chỉ có thể ghi tài liệu vào đúng nguồn đó, và không thể đọc hay tìm kiếm bất cứ thứ gì. Đây là khóa an toàn nhất để giao cho một nền tảng tích hợp như Zapier. Hãy tạo nó trên trang của nguồn tại API keys (khóa API của nguồn) hoặc bằng POST /v1/sources/{source_id}/push-keys.

Khi khóa API không khả dụng

Khóa API là một phần của gói của tổ chức. Nếu gói không bao gồm khóa API, việc tạo khóa và mọi yêu cầu có khóa đều trả về 403 với mã api_keys.feature_disabled.