[智能体-478]：Coze（扣子）三种官方鉴权令牌完整详解

Coze OpenAPI 统一使用Authorization: Bearer {token}头鉴权平台定义三类标准访问凭证PAT 个人访问令牌Personal Access TokenSAT 服务访问令牌Service Access TokenOAuth Access TokenOAuth2.0 用户授权令牌一、三种令牌核心对比总表表格维度PAT 个人访问令牌针对管理员账号SAT 服务访问令牌针对服务OAuth Access Token临时生成身份主体登录 Coze 的个人账号独立服务 / 后端应用身份企业版专属终端终端用户身份C 端用户、渠道用户令牌前缀pat_xxxxsat_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 OpenAPI4. 限制个人免费版无 SAT 入口必须升级企业版才能创建。四、3. OAuth Access Token多用户 C 端渠道接入1. 定义基于 OAuth2.0 标准流程生成的短时令牌代表终端普通用户身份实现多用户会话隔离是面向 C 端产品的标准方案扣子。2. 生成逻辑区别 PAT/SAT不能后台直接创建必须走授权流程后台创建 OAuth 应用分配 ClientID、ClientSecret用户在你的网页 / 小程序点击授权跳转 Coze 同意页面授权成功后回调业务后端换取短时 Access TokenToken 有效期 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 后的字符串httpAuthorization: Bearer 你的PAT/SAT/OAuth令牌以流式 curl 完整示例PATbash运行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 短时生效前端仅临时持有后端保管刷新凭证三种令牌泄露均会产生扣费风险务必最小化权限配置。