跳转到主内容

认证

Creatoria Agent API 文档

#认证

所有 API 请求都需要通过认证。Creatoria Agent API 使用 API Key 进行身份验证。

#API Key 认证

在每个请求的 Header 中传入 API Key：

X-API-Key: sk_your_api_key_here

#示例

bashcurl -X GET "https://your-domain.com/v1/agents" \
  -H "X-API-Key: sk_your_api_key_here"

#Project 上下文

部分操作（如创建 Agent）需要 Project 上下文。通过 X-Project-Id 请求头传入：

X-Project-Id: proj_abc123

如果 API Key 本身已绑定了 Project，则无需额外传入此头。但如果 API Key 没有绑定 Project，创建 Agent 等操作需要显式指定。

#权限与角色

API Key 的权限通过其 permissions 字段控制，映射到以下角色：

API Key 权限映射角色允许操作
adminadmin所有操作（GET、POST、PATCH、PUT、DELETE）
writemember读取和写入操作（GET、POST、PATCH）
readviewer仅读取操作（GET）

#权限检查规则

每个端点都声明了所需的权限，例如：

权限标识说明
agents:create创建 Agent
agents:update更新 Agent
agents:delete删除 Agent
agent:chat与 Agent 对话
session:create创建会话
session:read查看会话
session:update更新会话
session:delete删除会话
messages:read查看消息历史
kb:read查看知识库
kb:create创建知识库
kb:write更新知识库
kb:delete删除知识库
kb:upload上传文档
rag:search搜索知识库
tools:create创建工具配置
tools:update更新工具配置
tools:delete删除工具配置
webhooks:create创建 Webhook
webhooks:read查看 Webhook
webhooks:update更新 Webhook
webhooks:delete删除 Webhook

#多租户架构

Creatoria 使用三级租户架构：

Organization (组织)
  └── Project (项目)
       └── Agent (智能体)
  • Organization: 最顶层的隔离单元，拥有独立的资源和配额
  • Project: 项目级别的隔离，用于管理不同的业务场景
  • Agent: 最小的资源单元，属于某个 Project

API Key 在创建时会关联到 Organization，可选关联到特定 Project。

#安全建议

  1. 不要将 API Key 暴露在前端代码中，仅在后端服务器中使用
  2. 为不同环境使用不同的 API Key（开发、测试、生产）
  3. 定期轮换 API Key，删除不再使用的 Key
  4. 使用最小权限原则：只赋予 API Key 实际需要的权限
下一篇: Agents API →