Phạm vi quyền của khóa
Phạm vi quyền chỉ một phần của API mà khóa được phép gọi. Mỗi endpoint trong tài liệu tham chiếu API
khai báo một phạm vi mà nó cần. Yêu cầu với khóa thiếu phạm vi đó bị từ chối với 403 và mã
api_keys.scope, trước khi bất cứ thứ gì được đọc hoặc thay đổi.
Phạm vi quyền cho biết khóa được gọi những thao tác nào. Vai trò, hồ sơ dữ liệu và bộ sưu tập của khóa vẫn quyết định
những thao tác đó nhìn thấy đối tượng nào: khóa có cards:write và vai trò viewer không thể thay đổi thẻ, còn khóa
bị giới hạn trong một bộ sưu tập không nhìn thấy các bộ sưu tập khác.
Phạm vi quyền
| Phạm vi | Cho phép |
|---|---|
cards:read | Đọc thẻ, bộ sưu tập và thư mục. |
cards:write | Tạo, thay đổi và xóa thẻ, bộ sưu tập và thư mục. |
search | Tìm kiếm trong cơ sở tri thức (POST /v1/search). |
ask | Đặt câu hỏi cho trợ lý (POST /v1/ask, POST /v1/chat). |
import:write | Ghi vào các nguồn tùy chỉnh của tổ chức: đồng bộ, lô và thao tác xóa, và đọc trạng thái của chúng. Việc tạo nguồn và khóa của nguồn cần admin. |
webhooks:manage | Quản lý webhook và đọc nguồn cấp sự kiện (GET /v1/webhook-events). Cả hai việc đều cần thêm vai trò admin. |
users:read | Đọc người dùng và nhóm. |
users:write | Thay đổi người dùng và nhóm. |
analytics:read | Đọc số liệu phân tích. |
audit:read | Đọc nhật ký kiểm toán. |
finance:read | Đọc báo cáo tài chính, hóa đơn và khoản thanh toán. |
catalog:read | Đọc catalog dịch vụ. |
files:read | Đọc các tệp được tạo ra, chẳng hạn câu trả lời đã xuất. |
files:write | Thay đổi và xóa các tệp được tạo ra. |
permissions:manage | Gán và thu hồi quyền trên đối tượng. |
admin | Cài đặt của tổ chức và các khóa API của tổ chức. Khóa có admin cũng có mọi phạm vi khác. |
Tìm kiếm và đặt câu hỏi về bản chất là thao tác đọc: khóa chỉ được đọc vẫn có thể tìm kiếm và đặt câu hỏi.
Chọn phạm vi quyền
Chỉ cấp những phạm vi mà tích hợp sử dụng, không gì thêm:
| Tích hợp | Phạm vi |
|---|---|
| Bot hỏi đáp trong công cụ trò chuyện | search, ask |
| Nhập từ hệ thống tài liệu của bạn | cards:write (API thẻ) hoặc import:write (nguồn tùy chỉnh) |
| Xuất sang kho dữ liệu | cards:read, users:read và webhooks:manage cho nguồn cấp sự kiện |
| Cấp tài khoản người dùng từ hệ thống nhân sự của bạn | users:write |
Truyền danh sách này khi bạn tạo khóa:
curl -X POST https://api.sursa.com/v1/api-keys \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'Phạm vi quyền trước đây
Các khóa được tạo trước khi phạm vi quyền được chia nhỏ vẫn tiếp tục hoạt động. Các phạm vi read, write và admin
của chúng tương ứng với các tập sau:
| Phạm vi trước đây | Nghĩa là |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | mọi thứ trong read, cộng thêm cards:write, files:write, users:write, permissions:manage |
admin | mọi phạm vi |
Khóa được tạo mà không chỉ rõ phạm vi sẽ nhận phạm vi theo vai trò của nó: admin nhận admin; editor và
verifier nhận write; viewer nhận read.
Xem phạm vi quyền của khóa
GET /v1/me trả về các phạm vi của khóa gửi yêu cầu, dù khóa đó có phạm vi nào. Với khóa
được tạo mà không chỉ định phạm vi rõ ràng, đó là các phạm vi cũ của vai trò, chẳng hạn read và write; bảng ở
trên cho biết chúng tương ứng với gì. Khi một thao tác thất bại với api_keys.scope, error.message cho biết phạm vi
còn thiếu.