API Key 管理
管理访问密钥的 scope、执行目标、能力和后台任务配额。
API Key 用于服务端调用。登录 Token 用于当前账号的管理操作。先明确调用目的，再选择 scope 和执行目标，具体鉴权头见 鉴权。
scope 与权限
| scope | 对话、会话与产物 | 换取登录 Token | Office Mode |
|---|---|---|---|
conversation | 支持，受用户与具体 Key 归属限制 | 不支持 | 不支持 |
global | 支持，同样受归属限制 | 普通用户支持；管理员需要 admin Key | 不支持 |
admin | 支持，同样受归属限制 | 所属用户当前仍是管理员时支持 | 支持，仍受内容隐私规则限制 |
scope 不会把普通用户提升为管理员，也不让不同 Key 交叉访问已绑定的会话。管理员 scope 的创建和调用还检查账号管理角色。
执行目标
对话范围的 Key 可使用自由模式，也可通过 agent_id 绑定单个专家或专家团。创建后不能更换执行目标；需要不同目标时创建新 Key。非 conversation Key 不能绑定执行目标。
- 自由模式：从 Key 的
capability_config装配能力。 - 单专家：能力来自专家，使用当前账号自己的连接授权。
- 专家团：新会话采用当时团队编排；续聊保留该会话快照，模型和连接账户按运行规则解析。
显式模型配置可覆盖执行目标默认；请求中的 model 是协议字段，不直接选择 POCO 模型配置。绑定团队时先检查成员和依赖是否就绪；目标被删除、停用或授权不可用时返回错误。
管理端点
以下接口使用 Authorization: Bearer <poco-login-token>，不能直接把原始 API Key 当登录 Token。成功和业务响应为 {code,message,data}。
| 方法与路径 | 用途 |
|---|---|
GET /api/v1/api-access-keys | 列出自己的 Key，返回预览与后台计数 |
POST /api/v1/api-access-keys | 创建 Key，返回完整 api_key |
PATCH /api/v1/api-access-keys/{key_id} | 修改名称、有效期、可修改的模型与能力设置 |
DELETE /api/v1/api-access-keys/{key_id} | 删除 Key |
POST /api/v1/api-access-keys/{key_id}/copy | 读取自己的完整 Key 以便复制 |
GET /api/v1/api-access-keys/{key_id}/sessions | 查看该 Key 会话，limit 默认 50、最大 100，offset 默认 0 |
自由模式创建示例：
curl -X POST 'https://<poco-host>/api/v1/api-access-keys' \
-H 'Authorization: Bearer <poco-login-token>' \
-H 'Content-Type: application/json' \
-d '{"name":"report-service","scope":"conversation","capability_config":{"browser_enabled":false}}'创建 Schema 要求 name 和 capability_config；expires_at 可为 ISO 时间或 null，model_config_id 可指定可用模型配置。绑定专家时仍提交 capability_config 字段，但实际能力由绑定目标提供。列表只显示 key_preview，完整 Key 由创建或复制操作返回。
后台计数与隔离
列表包含 background_pending_runs、background_running_runs 和 background_pending_limit。默认每 Key 最多 20 个未完成后台 Run、最多 2 个运行，同一用户合计最多 50 个未完成 Run；这不是所有普通对话的通用并发上限。
读取已绑定的会话、后台结果和产物使用创建或绑定任务时的同一 Key。新业务请求使用新的幂等键，重试原请求保留原键。后台排队和结果查询参见 Messages 与 会话管理。
Key 按业务系统拆分，设置合理有效期，保存在服务端。删除或过期会阻止后续 Key 调用；通过 Key 签发的登录 Token 有自己的有效期，账号禁用后登录 Token 也不可继续使用。