扣子编程支持应用程序通过 OAuth 授权码授权（Authorization Code Grant）的方式调用扣子编程 API。用户通过浏览器访问包含扣子编程功能的 Web 应用程序时，Web 应用程序重定向用户到扣子编程服务端以获取授权码（code），然后使用授权码向扣子编程服务端交换访问令牌。例如 Web 应用程序通过扣子编程 API 封装了扣子编程的查看 Bot 的详细信息和指定 Bot 对话等功能，用户使用这些功能之前，需要经由扣子编程服务端鉴权。

授权流程

Web 应用程序授权流程如下图所示。

具体流程说明如下：

1. 在扣子编程创建 OAuth 应用。
2. 应用程序调用 API 获取授权页面 URL和获取 OAuth Access Token，获取 OAuth 访问令牌。
3. 应用程序根据访问令牌调用扣子编程 API。

详细步骤如下：

1 创建 OAuth 应用

1. 登录扣子编程。

2. 在左侧导航栏选择 API & SDK。

3. 在顶部单击授权 > OAuth 应用页签。

4. 在 OAuth 应用页面右上角单击创建新应用，填写应用的基本信息。

   配置	说明
   应用类型	应用的类型，此处设置为普通。
   客户端类型	客户端类型，此处设置为Web 后端应用。
   应用名称	应用的名称，在扣子编程中全局唯一。
   描述	应用的基本描述信息。

5. 填写 App 的配置信息。

   配置	说明
   权限	应用程序调用扣子 API 时需要的权限范围。 说明 此处配置旨在于划定应用的权限范围，并未完成授权操作。创建 Oauth 应用后还需要参考后续操作完成授权。
   重定向 URL	重定向的 URL 地址。用户完成授权后，扣子编程的授权服务器将通过重定向 URL 返回授权相关的凭据。最多可添加 3 个不同的 URL 地址。 重定向 URL 仅支持 HTTP 和 HTTPs。为了保证数据传输安全，请勿在生产环境使用HTTP 协议地址。 对于测试场景，您可以指定引用本地机器的 URL，例如 http://localhost:8080。
   客户端 ID 和客户端密钥	客户端 ID 和客户端密钥均由扣子编程自动生成并配置。单击生成客户端密钥，并复制系统自动生成的客户端密钥。 客户端 ID：即 client id，是应用程序的公共标识符。 客户端密钥：即 client secret，仅应用程序和授权服务器有权访问的密钥。用于获取已登录用户的访问令牌。 说明 此客户端密钥仅显示一次。请将其保存到安全且易于访问的地方。不要与他人分享，或在其他环境中暴露。 支持生成多个客户端密钥，当您发现密钥泄露时，可以通过此方法进行密钥轮转。 扣子编程在任何时候都不会存储您的客户端密钥，扣子服务端仅存储符合行业规范的密钥摘要值。

6. 单击确定，完成配置。

2 获取访问令牌

1. 终端用户在 Web 应用程序中触发授权操作，例如点击和 Bot 对话的按钮。该动作对应扣子发起对话 API，应用程序需要获得扣子账号的授权。

2. Web 应用程序重定向用户到授权服务器以获取 code。
   应用程序通过302重定向方式发起 获取授权页面 URL API 请求。
   请求中携带 OAuth 应用的客户端 ID 和客户端密钥 、重定向 URL 等信息。请求示例如下：

   curl --location --request GET 'https://www.coze.cn/api/permission/oauth2/authorize?response_type=code&client_id=8173420653665306615182245269****.app.coze&redirect_uri=https://www.coze.cn/open/oauth/apps&state=1294848'
   

   Response Header 中的 location 字段中为跳转链接。例如https://www.coze.cn/oauth/consent?authorize_key=JacVeqTW93ps5m5N9n349bEBgIsWrnNp。浏览器跳转到此 URL，引导用户完成扣子账号授权。授权页面示例如下：
   

   说明

   • 如果你是组织超级管理员和管理员，单击授权后，可以主动安装该应用。
   • 如果你是组织成员，单击授权后，如果系统提示授权失败，说明超级管理员或管理员未安装该应用，请单击发起申请。超级管理员或管理员收到安装请求后，在对话框中单击安装或在应用安装管理页面的操作列中单击安装。
   • 扣子支持多人协作场景下跨账号的 OAuth 授权，发起 获取授权页面 URL API 请求时如果指定空间 ID，空间协作者也可以为应用程序授予团队空间中的资源权限。详细说明可参考OAuth 授权（多人协作场景）。

3. 扣子服务端会在 API 的响应中返回 code。
   从重定向的 URL 地址中获取 code，例如本示例中 code 为 code_WZmPRDcjJhfwHD****。

   https://www.coze.cn/open/oauth/apps?code=code_WZmPRDcjJhfwHD****&state=1294848
   

4. 使用授权码交换访问令牌。
   应用程序向扣子服务端发起 获取 OAuth Access Token 请求，请求中携带 code，扣子服务端会在 API 的响应中返回 access_token 和 refresh_token。其中：

   • access_token 即访问令牌，用于发起扣子 API 请求时鉴权，有效期为 15 分钟。
   • refresh_token 用于刷新 access_token，有效期为 30 天。refresh_token 到期前可以多次调用 刷新 OAuth Access Token 接口获取新的 refresh_token 和 access_token。
     接口示例如下：
   请求示例 响应示例

   curl --location --request POST 'https://api.coze.cn/api/permission/oauth2/token' \
   --header 'Authorization: Bearer hDPU8gexPcwChkhMvmjvR14yQ1HWoaB42tCd0rjrc55G****' \
   --header 'Content-Type: application/json' \
   --data '{
       "grant_type": "authorization_code",
       "client_id": "8173420653665306615182245269****.app.coze",
       "redirect_uri": "https://www.coze.cn/open/oauth/apps",
       "code": "bfiqrhedxsdvnuivher****"
   }'
   

   {
       "access_token": "czu_UEE2mJn66h0fMHxLCVv9uQ7HAoNNS8DmF6N6grjWmkHX2jPm8SR0tJcKop8v****",
       "expires_in": 1720098388,
       "refresh_token": "LBEP9iWU7rn60PWa58GER5rr6vygb5WSACu2vASlCQu7kpFkavCrNa9BBDpHLUlGd46a****"
   }
   

3 发起扣子 API 请求

在 API 请求头中通过 Authorization=Bearer $Access_Token 指定访问令牌，发起扣子 API 请求。每个接口对应的权限点不同。
以获取已发布智能体的配置（即将下线） API 为例，完整的 API 请求如下：

curl --location --request GET 'https://api.coze.cn/v1/bot/get_online_info?bot_id=73428668*****' \ 
--header 'Authorization: Bearer czu_UEE2mJn66h0fMHxLCVv9uQ7HAoNNS8DmF6N6grjWmkHX2jPm8SR0tJcKop8v****' \

获取授权页面 URL

Web 应用程序可调用此 API 获取 OAuth 授权页面 URL 地址。

基础信息

Path 参数

Query

返回结果

返回结果的 Http code 为 302，且 Response Header 中的 location 字段中为跳转链接。例如https://www.coze.cn/oauth/consent?authorize_key=JacVeqTW93ps5m5N9n349bEBgIsWrn****。浏览器跳转到此 URL，引导用户完成 Coze 账号授权。

示例

请求示例

curl --location --request GET 'https://www.coze.cn/api/permission/oauth2/authorize?response_type=code&client_id=8173420653665306615182245269****.app.coze&redirect_uri=https://www.coze.cn/open/oauth/apps&state=1294848'

返回示例

https://www.coze.cn/oauth/consent?authorize_key=JacVeqTW93ps5m5N9n349bEBgIsW****

获取 OAuth Access Token

通过授权码（OAuth code）获取 OAuth Access Token。

基础信息

Header

Body

返回结果

示例

请求示例

curl --location 'https://api.coze.cn/api/permission/oauth2/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer czvSJMcRob40yQ04HmSyCbEw6h22r0LJwHcKyu13H2ic****' \
--data '{
    "grant_type": "authorization_code",
    "code": "code_hS0m5XlDLSAwWjaadftNqiOGAmOW02wSDiGunZETWQuR****",
    "redirect_uri": "https://coze.com/",
    "client_id": "9767336922475223578182683125****.app.coze"
}'

返回示例

{
    "access_token": "czu_UEE2mJn66h0fMHxLCVv9uQ7HAoNNS8DmF6N6grjWmkHX2jPm8SR0tJcKop8v****",
    "expires_in": 1720098388,
    "refresh_token": "LBEP9iWU7rn60PWa58GER5rr6vygb5WSACu2vASlCQu7kpFkavCrNa9BBDpHLUlGd4****"
}

刷新 OAuth Access Token

根据 refresh_token 获取新的 OAuth Access Token。
调用获取 OAuth Access Token API 获取的 OAuth Access Token 有效期为 15 分钟，refresh_token 有效期为 30 天。refresh_token 有效期内可以调用此 API 获取新的 OAuth Access Token。
接口调用成功后，入参中指定的 refresh_token 失效。

基础信息

Header

Body

返回结果

示例

请求示例

curl --location 'https://api.coze.cn/api/permission/oauth2/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer czvSJMcRob40yQ04HmSyCbEw6h22r0LJwHcKyu13H2ic****' \
--data '{
    "grant_type": "refresh_token",
    "refresh_token": "1gCCMSkz6F4u0br1zJwoNhK041SToNentkilrWFaKzUVK9c3dds3e5DVn23f1ROkflYf****",
    "client_id": "9767336922475223578182683125****.app.coze"
}'

返回示例

{
    "access_token": "czu_UVbDyB94NwXsMTJEvIwPp15oJycgl1y4rFoy774L9eFA0eKxmWGyUKbUt2uB****",
    "expires_in": 1720853011,
    "refresh_token": "NYbHWyusGWA03Ar1dpUMr6iuImN9bydfwRWWKpcKqcpTN9sDwmCxopt7Jg7HW6DGJnXL****"
}

错误码

常见问题

如何处理 OAuth 授权码授权失败，提示“OAuth 错误/请求参数错误”？

请检查回调地址中的特殊字符是否已正确转义。例如，回调地址中的 # 需要转义为 %23。确保所有特殊字符都已按照URL 编码规则进行转义，然后重新尝试授权。