状态：Experimental（Management）/ Preview（Interaction 接入） — App、API Key、Scope 与浏览器 Token 交换已有实现；它们是接入治理能力，不代表统一 Management Protocol 已达到 Preview。具体字段、默认 Scope 与 Console 操作以部署版本为准。
Integration App 是第三方嵌入的治理单元：独立 App ID、API Key、Scope 与审计边界。与 HARP 可安装应用、Console 运维 Token、用户 Session 严格区分。
核心概念
| 概念 | 前缀 | 说明 |
|---|---|---|
| 接入应用 | app_ | 公开标识，可写入 SDK |
| API Key | fkey_ | 私密凭证，创建时展示一次 |
| runtimeUserId | — | App 绑定的 harness 用户，决定 Agent/Skills/MCP 配置 |
| external_user_id | — | 第三方用户标识，用于 thread 分区（非 Fellow 账号） |
架构
第三方后端 Authorization: Bearer fkey_…
│
▼
Gateway app-auth → integrationApp + runtimeUserId
│
▼
Thread / Run（打标 integrationAppId）
│
▼
Harness（runtimeUserId 的配置）Embed 创建的 thread 不会出现在 Web Inbox（integrationAppId IS NULL 过滤）。
Scopes
| Scope | 能力 |
|---|---|
threads:write | 创建 thread、上传文件 |
threads:read | 读 thread、artifact、workspace 文件 |
runs:write | 创建 run、cancel、inject、consent |
runs:read | stream、run 状态与事件 |
consent:read / consent:write | 人机确认 |
默认授予上述六项。/api/workspaces CRUD 与 /api/console/* 不在 Integration App 开放范围内。
Console 管理
在 接入应用 页面：
- 创建 App / 轮换 Key
- 配置
allowed_origins（浏览器 embed CORS） - 设置
default_agent、runtimeUserId - 查看用量与 embed 对话列表
Access Token
POST /api/apps/token
Authorization: Bearer fkey_…
{ "origin": "https://your-app.com", "external_user_id": "user-123" }响应：{ access_token, token_type, expires_in, app_id }
多用户
同一 (integrationAppId, external_user_id) 会自动复用 active thread，适合 CRM 详情页等长期嵌入场景。