Xác thực

Tích hợp gọi với tư cách một chủ thể dịch vụ

Một tích hợp không đăng nhập như một người. Nó gọi với tư cách một chủ thể dịch vụ (service principal), bằng một khóa API gửi trong header Authorization:

curl -sS "$ORIGIN/api/v1/caller" \
  -H "Authorization: Bearer $AGENTFLOW_KEY"

Khóa có dạng afk_…. Cách tạo chủ thể, cấp khóa, xoay vòng và thu hồi khóa nằm ở Chủ thể dịch vụ.

Quyền thực tế của một yêu cầu

Quyền của một yêu cầu được tính lại ở mỗi lần gọi, bằng phép giao của hai thứ:

• các quyền hiện tại từ vai trò của chủ thể;
• phạm vi quyền của khóa.

Từ đó suy ra ba điều:

• Phạm vi quyền của khóa chỉ thu hẹp được. Nó được chốt lúc cấp khóa. Đánh dấu một quyền mà vai trò không có thì không thêm được gì; muốn đổi phạm vi, hãy cấp khóa mới.
• Sửa vai trò có hiệu lực ngay từ yêu cầu kế tiếp, cho mọi khóa của chủ thể đó.
• Phạm vi hồ sơ vẫn áp dụng. Với thực thể ở chế độ Hạn chế, chủ thể còn cần một lượt cấp quyền trên chính thực thể đó — xem Quyền truy cập Thực thể & Bản ghi.

GET /caller: khóa đang hành động với tư cách ai

GET /api/v1/caller cho biết yêu cầu đang hành động với tư cách ai, và nó được làm gì ngay lúc này. Đây là cách nhanh nhất để kiểm tra một khóa trước khi làm việc gì khác.

{
  "kind": "service_principal",
  "id": "5b0e2f4c-…",
  "display_name": "Invoice Import",
  "org_id": "9c41d7a0-…",
  "credential_id": "e27a91b3-…",
  "permissions": ["entity.list", "entity.read", "entity.write"],
  "email": null,
  "org_name": "Acme",
  "app": null
}

GET /app/objects: một ứng dụng được dùng những gì

GET /api/v1/app/objects chỉ dành cho ứng dụng đã cài đặt (thao tác đánh dấu x-app-only). Nó cho ứng dụng biết những đối tượng nào của tổ chức nó được dùng — thực thể, trường, quy trình, biểu mẫu và các loại khác — và mỗi đối tượng đang ở state nào: live, deprecated, hoặc off khi nó thuộc một tính năng tùy chọn đang tắt (khi đó key, id và contract là null). Đối tượng nằm ngoài phạm vi ứng dụng được duyệt, và đối tượng đã gỡ, không có trong danh sách. Câu trả lời gồm revision, mảng objects xếp theo logical_key, và parameters: giá trị mà lần cài đặt đang giữ cho từng tham số của ứng dụng, theo khóa — id của nhóm, người dùng, đơn vị hay chủ thể dịch vụ mà tham số trỏ tới, hoặc văn bản, số hay lựa chọn đã nhập. Tham số chưa có giá trị thì không có trong đó, và tham số secret_ref hay connection_ref thì không bao giờ có: các bước dùng đến chúng tự phân giải chúng trên máy chủ. Mọi phản hồi cho một yêu cầu mà lần cài đặt của ứng dụng đã cho qua còn mang header AgentFlow-App-Revision: bản sửa đổi của lần cài đặt tại lúc yêu cầu được cho qua. Đó là một số nguyên dương chỉ tăng, và có thể cũ hơn bản hiện tại. Phản hồi 401, APP_NOT_ASSIGNED và APP_NOT_INSTALLED do bước xác thực trả về không mang header này, vì bước xác thực từ chối các yêu cầu đó trước khi cho qua. Riêng GET /app/objects mang đúng bản sửa đổi mà nội dung của nó được đọc tại đó. Hãy lưu danh sách cùng số này, và chỉ gọi lại GET /app/objects khi một phản hồi mang số lớn hơn số bạn đang giữ. Một yêu cầu không đi qua ứng dụng đã cài đặt — khóa của chủ thể dịch vụ, hay token của một người — nhận 403 APP_CALLER_REQUIRED; yêu cầu chưa xác thực nhận 401.

Người dùng: token riêng chỉ dành cho MCP

Token của một người chỉ dùng tại điểm cuối MCP, khi một trợ lý AI bên ngoài (ví dụ Claude Desktop) làm việc thay người đó, với đúng quyền của người đó. Một người không gọi API REST bằng token của mình.

• Bật một quy trình cho trợ lý bên ngoài: Chia sẻ quy trình qua MCP.
• Mở AgentFlow như một máy chủ MCP: Máy chủ MCP.
• Khóa cho tích hợp dùng MCP: Chủ thể dịch vụ.
• Các công cụ và lỗi của chúng: Công cụ MCP.

Cookie phiên chỉ dành cho ứng dụng AgentFlow

Ứng dụng web AgentFlow xác thực bằng cookie phiên đăng nhập. Cookie đó chỉ dành cho chính ứng dụng; một tích hợp không dùng nó.

Khi xác thực hoặc phân quyền bị từ chối

Một tài nguyên mà bạn không được phép thấy thì trả 404, không phải 403 — xem Lỗi.