Xác thực

Mọi yêu cầu tới Sursa API đều mang khóa API, hoặc token truy cập OAuth của một ứng dụng, trong header Authorization:

Authorization: Bearer kb_3f9c…

Khóa xác định tổ chức và quyết định yêu cầu được xem và thay đổi những gì: vai trò, phạm vi quyền, hồ sơ dữ liệu và bộ sưu tập của khóa. Trên địa chỉ API không có phiên hay cookie. Mỗi yêu cầu được xác thực riêng, nên bạn có thể gửi yêu cầu song song và từ nhiều máy chủ với cùng một khóa.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Các tích hợp trước đây có thể gửi khóa trong header X-API-Key. Cách này vẫn được chấp nhận, nhưng mã mới nên dùng Authorization: Bearer.

Các loại thông tin xác thực

Thông tin xác thực	Dạng	Nơi hoạt động
Khóa API của tổ chức	`kb_…`	Mọi endpoint của API, trong giới hạn vai trò, phạm vi quyền, hồ sơ dữ liệu và bộ sưu tập của khóa.
Khóa của nguồn tùy chỉnh	`kbsrc_…`	Chỉ các endpoint đẩy dữ liệu của chính nguồn tùy chỉnh đó (`/v1/push/sources/{source_id}/…`).
Token truy cập OAuth	`kbat_…`	Các endpoint trong tài liệu tham chiếu API, trong giới hạn phạm vi quyền của token. Token nhận từ `POST /oauth/token` bằng mã ủy quyền hoạt động thay mặt nhân viên đã đồng ý; token `client_credentials` hoạt động thay mặt tổ chức, giống như khóa API. Token có hiệu lực trong 1 giờ.

Tất cả được gửi theo cùng một cách. Khóa của nguồn tùy chỉnh không thể đọc, tìm kiếm hay thay đổi bất cứ thứ gì ngoài nguồn của nó; hãy dùng nó ở nơi khóa được bên thứ ba lưu giữ, chẳng hạn một nền tảng tích hợp.

Lỗi xác thực

Trạng thái và mã	Ý nghĩa	Cách xử lý
`401` `auth.not_authenticated`	Không có khóa, khóa gõ sai hoặc khóa đã bị thu hồi.	Kiểm tra header và giá trị khóa.
`401` `api_keys.expired`	Khóa đã quá ngày hết hạn.	Tạo khóa mới và thay thế khóa cũ.
`401` `sources.push_key_invalid`	Khóa của nguồn tùy chỉnh sai, đã bị thu hồi hoặc thuộc về nguồn khác.	Kiểm tra khóa và ID nguồn trong đường dẫn.
`401` `oauth.token_expired`	Token truy cập OAuth đã hết hạn.	Lấy token mới bằng token làm mới.
`403` `api_keys.scope`	Khóa không có phạm vi quyền cho thao tác này.	Thêm phạm vi, hoặc dùng khóa có phạm vi đó.
`403` `api_keys.feature_disabled`	Gói của tổ chức không bao gồm khóa API.	Liên hệ quản trị viên của tổ chức.
`403` `api_keys.ip_not_allowed`	Yêu cầu đến từ một địa chỉ nằm ngoài các địa chỉ được phép của khóa.	Gọi từ một mạng được phép, hoặc thay đổi các địa chỉ của khóa.
`403` `api_keys.mcp_only`	Khóa MCP cá nhân được dùng ngoài endpoint `/mcp`.	Dùng khóa API của tổ chức cho API.
`403` `oauth.operation_not_allowed`	Thao tác không thuộc API công khai, nên token OAuth không thể gọi nó.	Dùng một thao tác trong tài liệu tham chiếu API.
`403` `org.suspended`	Tổ chức bị tạm ngừng. Dữ liệu của tổ chức vẫn được giữ.	Liên hệ quản trị viên của tổ chức.

403 nghĩa là yêu cầu đã được xác thực nhưng không được phép. Đối tượng mà khóa không được phép xem trả về 404, giống như đối tượng không tồn tại, nên khóa không thể biết được những gì nằm ngoài quyền truy cập của nó.

Thực hiện với tư cách một hồ sơ dữ liệu

Khóa có vai trò admin có thể kiểm tra một nhóm người khác sẽ nhìn thấy gì: header X-View-As chạy yêu cầu với tư cách một hồ sơ dữ liệu và, nếu cần, một vai trò.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Yêu cầu ở chế độ này chỉ đọc: mọi thay đổi đều trả về 403 với mã view_as.read_only. Token OAuth, hoặc khóa không có vai trò admin, không thể dùng X-View-As: yêu cầu trả về 403 với mã view_as.admin_key_required. Header không chỉ tới hồ sơ nào đang tồn tại trả về 400 với mã view_as.invalid_header.

Ứng dụng trên trình duyệt

API cho phép yêu cầu từ mọi web origin (Access-Control-Allow-Origin: *) và không bao giờ dùng cookie, nên một trang web có thể gọi API bằng fetch. Khi đó khóa nằm trong trang và hiển thị với bất kỳ ai dùng trang đó. Chỉ gọi API từ trình duyệt bằng khóa mà bạn sẵn sàng cho những người dùng đó nhìn thấy, chẳng hạn khóa viewer giới hạn trong các bộ sưu tập công khai, hoặc đặt máy chủ của riêng bạn giữa trình duyệt và Sursa.

Những gì chỉ nhân viên mới làm được

Khóa API của tổ chức hoạt động thay mặt tổ chức, không phải thay mặt một người. Hai phần của API thuộc về con người, nên chúng chỉ hoạt động với token thay mặt một nhân viên: một phiên trong Sursa hoặc một token truy cập OAuth được cấp với sự đồng ý của nhân viên đó.

Cuộc trò chuyện thuộc về một người. Trong GET /v1/conversations, khóa API của tổ chức chỉ thấy những cuộc trò chuyện do chính nó bắt đầu. API công khai không có thao tác nào bắt đầu cuộc trò chuyện, nên với một khóa, danh sách này thường trống, và cuộc trò chuyện của nhân viên không bao giờ hiển thị với khóa. Câu hỏi không gắn với cuộc trò chuyện, gửi bằng POST /v1/ask hoặc POST /v1/chat, hoạt động với mọi khóa có phạm vi ask. Để liệt kê cuộc trò chuyện của một nhân viên và đọc lịch sử của một cuộc bằng GET /v1/conversations/{conv_id}, hãy gọi API bằng token OAuth thay mặt nhân viên đó. Token chỉ thấy cuộc trò chuyện của chính nhân viên đó; mọi cuộc trò chuyện khác trả về 404 với mã conversations.not_found.

Chỉ nhân viên mới kiểm chứng thẻ. Việc kiểm chứng xác nhận rằng một người đã kiểm tra nội dung, nên POST /v1/cards/{card_id}/verification/verify và POST /v1/cards/{card_id}/verify cần một phiên hoặc token OAuth thay mặt một nhân viên được phép kiểm chứng thẻ. Với khóa API của tổ chức, hoặc token client_credentials, hai thao tác này trả về 400 với mã cards.verify_user_account_required. Các bước kiểm tra thông thường diễn ra trước: thẻ mà khóa không thể xem trả về 404, còn khóa không được phép kiểm chứng thẻ trả về 403.