[智能体-478]：Coze（扣子）三种官方鉴权令牌完整详解
Coze OpenAPI 统一使用Authorization: Bearer {token}头鉴权，平台定义三类标准访问凭证：
- PAT 个人访问令牌（Personal Access Token）
- SAT 服务访问令牌（Service Access Token）
- OAuth Access Token（OAuth2.0 用户授权令牌）
一、三种令牌核心对比总表
表格
| 维度 | PAT 个人访问令牌 （针对管理员账号） | SAT 服务访问令牌 （针对服务） | OAuth Access Token （临时生成） |
|---|---|---|---|
| 身份主体 | 登录 Coze 的个人账号 | 独立服务 / 后端应用身份（企业版专属） | 终端终端用户身份（C 端用户、渠道用户） |
| 令牌前缀 | pat_xxxx | sat_xxxx | 无固定前缀，短时随机串 |
| 有效期 | 最长 30 天，不可永久 | 支持永久有效 | 短时（默认 2 小时），需刷新 |
| 生成入口 | API 授权→个人访问令牌 | API 授权→服务访问令牌 | OAuth 应用授权流程换取 |
| 适用场景 | 本地 curl 调试、Playground、测试脚本、临时开发 | 企业生产后端服务、K8s 常驻服务、定时任务、长期调用智能体 API | 官网 / 小程序 / APP/H5 前端，区分不同终端用户会话隔离 |
| 权限范围 | 账号名下所有空间， 按接口勾选权限 | 绑定指定空间、Bot， 服务级细粒度权限 | 仅授权用户允许访问的 Bot， 隔离用户数据 |
| 安全等级 | 低（明文长时效，泄露风险高） | 中（长效但仅服务侧保管，不暴露前端） | 高（短时、用户隔离、无全局权限） |
| 版本限制 | 免费版 / 个人版全部可用 | 仅企业标准版 / 旗舰版开放 | 全版本可用， 需创建 OAuth 应用 |
| 典型用法 | curl 调试、本地脚本、快速验证接口 | 云原生微服务、后台常驻 AI 服务 | WebSDK、小程序、移动端、多用户渠道接入 |
二、1. PAT 个人访问令牌（调试专用）
1. 定义
以登录者个人账号身份调用 API 的临时密钥，前缀pat_，是前面写 curl、Playground 调试用的令牌扣子。
2. 生成路径
扣子后台 → 左侧「扣子 API」→ 授权 → 个人访问令牌 → 添加令牌
- 配置项：名称、过期时间（1/7/30 天）、权限（对话 chat、Bot 管理、知识库等）
- 仅创建时展示一次，务必复制保存，丢失无法找回
3. 特点
- 使用最简单，一行 curl 直接调用，无需复杂授权流程；
- 权限等于你的账号，能操作你所有空间、Bot、知识库；
- 最长仅 30 天，到期自动失效；
- 安全缺陷：硬编码在脚本 / 前端极易泄露，泄露后他人可操作你全部资源。
4. 适用场景
- 本地终端 curl 调试
/v3/chat流式智能体接口 - Coze Playground 在线测试 API
- 临时脚本、本地 Demo、测试环境验证
5. curl 示例鉴权头
bash
运行
-H "Authorization: Bearer pat_abc123xxxx"三、2. SAT 服务访问令牌（企业生产后端专用）
1. 定义
Service Access Token，独立服务身份凭证，前缀sat_，企业版专属，用于后端常驻服务调用 AI 智能体，替代 PAT 做生产环境鉴权。
2. 核心优势
- 可设置永久有效，无需每月轮换；
- 身份是独立服务，不和个人账号绑定，员工离职不影响线上服务；
- 权限隔离：仅授予指定空间、指定 Bot，最小权限管控；
- 鉴权写法与 PAT 完全一致，代码无需改动，直接替换 token 即可上线。
3. 适用场景
- K8s 部署的智能体推理服务、微服务后台
- 定时任务、知识库同步、工作流批量执行
- 企业内部系统长期调用 Coze OpenAPI
4. 限制
个人免费版无 SAT 入口，必须升级企业版才能创建。
四、3. OAuth Access Token（多用户 C 端渠道接入）
1. 定义
基于 OAuth2.0 标准流程生成的短时令牌，代表终端普通用户身份，实现多用户会话隔离，是面向 C 端产品的标准方案扣子。
2. 生成逻辑（区别 PAT/SAT）
不能后台直接创建，必须走授权流程：
- 后台创建 OAuth 应用（分配 ClientID、ClientSecret）；
- 用户在你的网页 / 小程序点击授权，跳转 Coze 同意页面；
- 授权成功后回调业务后端，换取短时 Access Token；
- Token 有效期 2 小时，过期需用 Refresh Token 刷新。
3. 四大授权流程（按需选择）
- 授权码模式（Web 前后端分离）：官网、PC 网页，有后端服务；
- PKCE 模式（无后端纯前端）：小程序、H5、浏览器单页应用；
- 设备码模式（CLI / 硬件设备）：单片机、终端硬件调用；
- JWT OAuth（纯后端渠道）：多租户 SaaS、第三方渠道批量对接。
4. 核心价值（PAT/SAT 无法实现）
用户数据完全隔离： 不同 C 端用户拿到不同 OAuth Token，调用同一个 Bot 时，conversation_id对话历史互相隔离，A 用户看不到 B 用户聊天记录； PAT/SAT 是全局身份，所有用户共用一套会话池，数据会混淆。
5. 适用场景
- 对外官网智能客服、小程序 AI 对话、APP 内置机器人
- 多租户 SaaS 平台，每个客户独立对话上下文
- 第三方渠道接入 Coze 智能体，区分渠道用户
五、选型决策指南（开发直接对照）
- 本地调试、写 curl 命令、Playground 测试→ 选 PAT
- 企业自有后端服务、K8s 云原生服务、长期后台任务→ 企业版选 SAT
- 对外网页 / 小程序 / APP，需要区分多个终端用户、隔离对话历史→ 选 OAuth Access Token
六、统一鉴权格式（三类 token 通用）
所有令牌 HTTP 头部写法完全一致，仅替换 Bearer 后的字符串：
http
Authorization: Bearer 你的PAT/SAT/OAuth令牌以流式 curl 完整示例（PAT）：
bash
运行
curl -N -L POST https://api.coze.cn/v3/chat \ -H "Authorization: Bearer pat_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{...}'七、关键安全注意事项
- PAT 禁止放到前端、客户端、公开代码仓库，仅本地测试使用；
- SAT 存放于后端环境变量、K8s Secret，绝不暴露给浏览器；
- OAuth Token 短时生效，前端仅临时持有，后端保管刷新凭证；
- 三种令牌泄露均会产生扣费风险，务必最小化权限配置。