Skip to main content

​
绑定授权与隔离

Skills 平台的安全基石是按授权绑定：每一个用户授权（consent grant）把「一个 Agent + 一个已授权用户 + 一项能力」绑成专属、不可交叉的三元关系。这种设计天然隔离了不同 Agent、不同用户的数据和权限，无需复杂的中央权限管理系统。 核心特点：
  • 天然隔离：每个 consent grant 的用户数据只对其绑定的 Agent 可见，跨 Agent 访问被永久拦截
  • 无权限膨胀：不存在 Admin、Super User 等特殊角色，权限明确且固定，按能力（scope）限定
  • 审计友好：每个授权关系清晰易追踪，便于日志审计和合规检查

​
双层认证

Skills 平台采用 API Key + 用户授权（consent grant） 的双层认证机制：
  1. API Key — 标识 Agent 身份（连接层），由 Agent 应用方保管
  2. 用户授权（consent grant） — 标识一个已授权的外卖用户，一个 consent grant 对应一个用户、默认 90 天有效，通过绑定流程（SMS 验证码 / H5）获得
每个用户必须本人授权一次。 平台不提供 Admin 静默绑定 —— 不存在任何后台凭据可以替用户跳过授权（旧版 ADMIN_SECRET / 受信绑定已移除）。用户只能通过 request_user_bind（SMS 默认 / H5）发起、再由本人 verify_user_bind 完成授权。

​
API Key（Agent 识别）

  • 前缀：clw_ 开头，后接随机字符，例如 clw_a1b2c3d4...
  • 存储：服务端只存哈希、不保留明文，每次请求按哈希比对
  • 颁发：在 Portal 创建 Agent 时生成，仅显示一次，遗失需重新生成
  • 使用：在连接层 HTTP Header 中作为 Authorization: Bearer {API_KEY} 传入，标识调用方 Agent
  • 前缀：cg_ 开头
  • 一对一：一个 consent grant 对应一个用户（绑「Agent + 用户 + 能力」三元关系）
  • 有效期：默认 90 天；到期或轮换后需用户重新绑定
  • 来源：用户通过绑定流程（SMS 验证码 / H5）本人授权后获得；verify_user_bind 成功返回 consent_grant_id、scopes、expires_at（ISO 8601）
  • 存储：明文仅本次返回一次，落库仅存哈希，请妥善保存
  • 传递：作为每个 MCP 工具的 consent_grant_id 参数传入（不放进 body，也不走请求头）
  • 失效：到达 expires_at 过期，或被 revoke_user_bind 撤销后即时失效，需重新绑定获取新的

​
数据加密

Skills 平台对所有敏感数据进行分层加密 / 哈希，确保即使数据库泄露也无法直接还原关键信息：
用户 ID 加密
  • 算法：AES-256-GCM
  • 密钥：由服务端安全生成和管理
  • 场景：用户 ID 在数据库中以密文存储
  • 解密权限：仅绑定的 Agent 可解密其对应的用户数据

​
Agent-User 隔离

Skills 平台在数据访问层强制执行严格的隔离策略：
实现细节：
  1. 每个授权类请求都携带 API Key 和 consent_grant_id
  2. 服务端验证 API Key，解析出 agent_id
  3. 服务端验证 consent_grant_id，定位已授权用户与其授权能力
  4. 数据库查询条件：WHERE agent_id = ? AND user_id = ?
  5. 任何跨越这两个条件的查询都会被拒绝（授权属于其它能力 / 服务商返回 CONSENT_GRANT_WRONG_CAP，能力未开通返回 CAP_NOT_BOUND）

​
用户授权生命周期

关键节点：

​
认证失败处理

认证 / 授权失败统一返回 {"error": {"code", "message"}} 结构，并附相应的 HTTP 状态码：

401 Unauthorized

凭证缺失或无效
  • 缺少 API Key（AUTH_REQUIRED）
  • API Key 无效或已禁用（AUTH_INVALID）
  • 缺少 consent_grant_id（CONSENT_GRANT_REQUIRED）
  • consent_grant_id 无效或已过期（CONSENT_GRANT_INVALID / CONSENT_GRANT_EXPIRED）

403 Forbidden

无权限访问
  • 授权属于其它能力 / 服务商（CONSENT_GRANT_WRONG_CAP）
  • 当前 Agent 未开通该能力（CAP_NOT_BOUND）

429 Too Many Requests

速率限制
  • 在限制时间内请求过多（RATE_LIMITED）
  • 每个 Agent 独立限流（下单 10 次/分钟，其他 60 次/分钟）

统一错误格式

{"error": {"code", "message"}}
  • 所有认证 / 授权 / 业务错误同构
  • 完整错误码见 错误处理
认证链与各端点的认证级别详见 认证机制。

​
安全最佳实践

  • 保管 API Key：存储在安全的环境变量或密钥管理系统中，不要提交到版本控制
  • 保管 consent_grant_id：安全存储用户授权凭证（明文仅返回一次），涉及用户敏感数据
  • HTTPS only：所有与 Skills API 的通信必须使用 HTTPS
  • 轮换与撤销：在 Portal 按需轮换 / 禁用 API Key（立即失效）；consent grant 重授权即轮换，并可随时 revoke_user_bind 撤销
  • 错误处理：捕获 401/403 错误，提示用户重新认证或重新绑定

​
常见问题