跳转到主内容

认证

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 的权限档位（scope）通过其 permissions 字段控制，映射到以下角色：

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

#权限检查规则

各端点文档标注了所需的权限档位，由其 HTTP 方法决定：

所需档位覆盖操作
read查看类操作（GET）——查看 Agent、会话、消息历史、知识库、工具配置、Webhook
write创建与更新类操作（POST、PATCH）——与 Agent 对话、创建/更新 Agent、会话、知识库、上传文档、知识库搜索、工具配置、Webhook
admin删除与完全控制类操作（PUT、DELETE）——删除 Agent、会话、知识库、工具配置、Webhook

使用低于所需档位的 API Key 请求将返回 403 Forbidden。

#多租户架构

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 →