纯后端应用通常不包含任何用户界面元素，用户无法直接与之交互。该场景下建议使用 JWT（JSON Web Token）模式，扣子账号直接永久授予 OAuth App 权限，OAuth App 随时可以通过后端应用签发的 JWT 获取访问令牌，以后端应用的身份请求扣子 API。

示例项目源码

使用 JWT 进行鉴权的步骤较为复杂，扣子编程提供了 Python 等多语言 SDK，能够有效简化鉴权流程，支持扣子编程的各种鉴权模式。推荐使用扣子 SDK 实现鉴权。以下是基于扣子 SDK 的 OAuth JWT 授权的示例代码，供参考：

授权流程

授权流程如下：

1. 在扣子编程创建 OAuth 应用并完成授权。
2. 应用程序通过公钥和私钥签署 JWT。
3. 应用程序通过 API，获取访问令牌，具体请参见通过 JWT 获取 Oauth Access Token 。
4. 应用程序根据访问令牌调用扣子 API。

详细步骤如下：

1 创建 Oauth 应用并授权

你需要在扣子编程中创建 OAuth 应用。

1. 登录扣子编程。

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

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

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

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

5. 填写应用的配置信息。
   

   配置	说明
   公钥和私钥	用于应用程序客户端身份认证的非对称密钥。 单击创建 Key，页面将自动创建一对公钥和私钥，公钥自动配置在扣子中，私钥以 private_key.pem 文件格式由网页自动下载至本地 Downloads 目录下。支持创建最多三对公钥和私钥。 说明 建议将 private_key.pem 文件安全地存储在只有您的应用可以访问的位置。 扣子编程使用符合行业标准的 WebCrypto 加密标准，在浏览器前端创建非对称密钥，密钥强度符合行业标准。扣子编程任何时候都不会上传私钥到后端。请您放心使用。
   权限	应用程序调用扣子 API 时需要的权限范围。不同层级权限的生效范围请参见权限层级。 说明 此处配置旨在于划定应用的权限范围，并未完成授权操作。创建 OAuth 应用后还需要参考后续操作完成授权。

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

7. 在弹出的对话框中，确认权限等信息无误后，单击授权。
   

2 签署 JWT

扣子编程的 JWT 生成方式及部分参数定义沿用业界统一流程规范，但 JWT 中 Header 和 Payload 部分由扣子编程自行定义。
在 JWT（JSON Web Tokens）的流程中，通常使用私钥来签署（sign）token。JWT 包含三部分，即 Header、Payload 和 signature，其中 header 和 payload 由参数拼接而成，signature 根据指定的签名算法和私钥对 Header 和 Payload 自动计算生成。三部分之间用点（.）分隔。详细的签署方式可参考JWT 官方文档。

Header 和 Payload

扣子编程对 Header 和 Payload 的定义如下：

• Header
  Header 部分的参数定义如下：

  参数	类型	是否必选	说明
  alg	String	必选	签名使用的加密算法，固定为 RS256。 RS256 是一种基于非对称加密的签名算法，它结合了 RSA 加密和 SHA-256 哈希算法。
  typ	String	必选	固定为 JWT。
  kid	String	必选	OAuth 应用的公钥指纹，可以在OAuth 应用页面找到这个应用，在操作列单击编辑图标，进入配置页面查看公钥指纹。

  Header 示例如下：

  {
    "alg": "RS256",          // 固定为RS256
    "typ": "JWT",            // 固定为 JWT
    "kid": "gdehvaDegW....." // OAuth 应用的公钥指纹
  }
  

• Payload：
  Payload 部分的参数定义如下：

  参数	类型	是否必选	说明
  iss	String	必选	OAuth 应用的 ID，可以在OAuth 应用页面查看。
  aud	String	必选	扣子 API 的 Endpoint，即 api.coze.cn。
  iat	Integer	必选	JWT 开始生效的时间，Unixtime 时间戳格式，精确到秒。一般为当前时刻。
  exp	Integer	必选	JWT 过期的时间，Unixtime 时间戳格式，精确到秒。必须晚于 iat。
  jti	String	必选	随机字符串，用于防止重放攻击。建议长度大于 32 字节。每次签署 JWT 时应指定为不同的字符串。
  session_name	String	可选	访问令牌的会话标识。目前仅限在会话隔离场景下使用，即将 session_name 指定为用户在业务侧的 UID，以此区分不同业务侧用户的对话历史。 若未指定 session_name，不同用户的对话历史可能会掺杂在一起。 说明 会话隔离的详细实现方法请参见如何实现会话隔离。
  session_context	Object	可选	会话上下文信息，包含设备相关信息等。
  session_context.device_info	Object	可选	用于配置设备相关信息，扣子编程基于该部分信息对设备做用量管控以及账单记录。 说明 仅扣子企业旗舰版支持该参数。硬件设备用量管控的具体操作可参考终端用户用量查询和配额管控。
  session_context.device_info.device_id	String	可选	IoT 等硬件设备 ID，一个设备对应一个唯一的设备号。 当需要记录设备用量或对设备用量进行管控时，需要填写该参数，否则，无法对设备进行用量管控，用量统计页面对应的设备 ID 将显示为 N/A。
  session_context.device_info.custom_consumer	String	可选	自定义维度的实体 ID，你可以根据业务需要进行设置，例如 APP 上的用户名等。 当需要记录设备用量或对设备用量进行管控，需要填写该参数，否则，无法对设备进行用量管控，用量统计页面对应的自定义 ID 将显示为 N/A。 说明 device_id 和 custom_consumer 建议选择其中一个即可。 custom_consumer 参数用于设备用量管控，与对话等 API 传入的 user_id 无关，user_id 主要用于上下文、数据库隔离等场景。 出于数据隐私及信息安全等方面的考虑，不建议使用业务系统中定义的用户敏感标识（如手机号等）作为 custom_consumer 的值。

  Payload 示例如下：

  {
      "iss": "310000000002",   // OAuth 应用的 ID
      "aud": "api.coze.cn",    // 扣子 API 的 Endpoint
      "iat": 1516239022,       // JWT 开始生效的时间，秒级时间戳
      "exp": 1516259022,       // JWT 过期时间，秒级时间戳
      "jti": "fhjashjgkhalskj", // 随机字符串，防止重放攻击
      "session_name": "user_2222",  //用户在业务侧的 UID
      "session_context": {
          "device_info": {
              "device_id": "1234567890" // IoT 等硬件设备的唯一标识 ID
          }
      }
  }
  

示例代码

你可以直接参考以下示例代码签署 JWT。

# You must run `pip install PyJWT cryptography` to install the PyJWT and the cryptography packages in order to use this script.

#!/usr/bin/env python3
import sys
import time
import uuid

import jwt

# 替换为你的实际 Coze App 私钥
signing_key = '''
-----BEGIN PRIVATE KEY-----
xxxxxxxxxxxxxxxxxx
-----END PRIVATE KEY-----
'''

payload = {
    'iat': int(time.time()),
    'exp': int(time.time()) + 600,
    "jti": str(uuid.uuid4()),
    'aud': 'api.coze.cn',   # 替换为实际的coze api domain
    'iss': '1127900106117'  # 替换为你的实际 Coze App ID
}

headers = {
    'kid': '_v0VjcMlLdQc3tRTD3jC5Xz29TUnKQOhtuD5k-gpyf4'  # 替换为你的实际 Coze App 公钥指纹
}

# Create JWT with headers
encoded_jwt = jwt.encode(payload, signing_key, algorithm='RS256', headers=headers)

print(f"JWT: {encoded_jwt}")

最终生成的 JWT 示例如下：

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InZZd2ZsdFR1OWZBbWtwWFhSdnR5UmREc3RONVMzZWNFcDFqVzB6dVQyRE****.eyJpc3MiOiIzMTAwMDAwMDAwMDIiLCJhdWQiOiJhcGkuY296ZS5jb20iLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTkxNjI1OTAyMiwianRpIjoiZmhqaGFsc2tqZmFkc2pld3F****.CuoiCCF-nHFyGmu2EKlwFoyd3uDyKQ3Drc1CrXQyMVySTzZlZd2M7zKWsziB3AktwbUZiRJlQ1HbghR05CW2YRHwKL4-dlJ4koR3onU7iQAO5DkPCaIxbAuTsQobtCAdkkZTg8gav9EnN1QN_1xq0w8BzuuhS7wCeY8UbaskkTK9GnO4eU9tEINmVw-2CrfB-kNbEHlEDwXfcrb4YPpkw3GhmuPShenNLObfSWS0CqIyakXL8qD5AgXLoB-SejAsRdzloSUInNXENJHfSVMkThxRhJy7yEjX3BmculC54fMKENRfLElBqwJyLLUjeRHsYnaru2ca4W8_yaPJ7F****

3 获取访问令牌

应用程序调用 通过 JWT 获取 Oauth Access Token API ，请求 Header 中携带 JWT，扣子服务端会在响应中通过 access_token 字段返回访问令牌。
请求示例如下：

curl --location --request POST 'https://api.coze.cn/api/permission/oauth2/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIyRE****.eyJpc3MiOiIzMTAwMDAwMDAwMDIiLCJhdWQiOiJhcGkuY296ZS5jb20iLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTkxNjI1OTAyMiwianRpIjoiZmhqaGFsc2tqZmFkc2pld3F****.CuoiCCF-nHFyGmu2EKlwFoyd3uDyKQ3Drc1CrXQyMVySTzZlZd2M7zKWsziB3AktwbUZiRJlQ1HbghR05CW2YRHwKL4-dlJ4koR3onU7iQAO5DkPCaIxbAuXfcrb4YPpkw3GhmuPShenNLObfSWS0CqIyakXL8qD5AgXLoB-SejAsRdzloSUInNXENJHfSVMkThxRhJy7yEjX3BmculC54fMKENRfLElBqwJyLLUjeRHsYnaru2ca4W8_yaPJ7F****' \
--data '{
    "duration_seconds": 86399,
    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
}'

curl --location --request POST 'https://api.coze.cn/api/permission/oauth2/account/7490888144456***/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InZZd2ZsdFR1OWZBbWtwWFhSdnR5UmREc3RONVMzZWNFcDFqVzB6dVQyRE****.eyJpc3MiOiIzMTAwMDAwMDAwMDIiLCJhdWQiOiJhcGkuY296ZS5jb20iLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTkxNjI1OTAyMiwianRpIjoiZmhqaGFsc2tqZmFkc2pld3F****.CuoiCCF-nHFyGmu2EKlwFoyd3uDyKQ3Drc1CrXQyMVySTzZlZd2M7zKWsziB3AktwbUZiRJlQ1HbghR05CW2YRHwKL4-dlJ4koR3onU7iQAO5DkPCaIxbAuTsQobtCAdkkZTg8gav9EnN1QN_1xq0w8BzuuhS7wCeY8UbaskkTK9GnO4eU9tEINmVw-2CrfB-kNbEHlEDwXfcrb4YPpkw3GhmuPShenNLObfSWS0CqIyakXL8qD5AgXLoB-SejAsRdzloSUInNXENJHfSVMkThxRhJy7yEjX3BmculC54fMKENRfLElBqwJyLLUjeRHsYnaru2ca4W8_yaPJ7F****' \
--data '{
    "duration_seconds": 86399,
    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
}'

返回示例如下：

{
    "access_token": "czs_RQOhsc7vmUzK4bNgb7hn4wqOgRBYAO6xvpFHNbnl6RiQJX3cSXSguIhFDzgy****",
    "expires_in": 1721135859
}

4 发起扣子 API 请求

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

curl --location --request GET 'https://api.coze.cn/v1/bots/73428668*****?is_published=true' \ 
--header 'Authorization: Bearer czu_UEE2mJn66h0fMHxLCVv9uQ7HAoNNS8DmF6N6grjWmkHX2jPm8SR0tJcKop8v****' \

通过 JWT 获取 Oauth Access Token

通过 JWT 获取 Oauth Access Token。

基础信息

请求参数

Header

Path

Body

返回参数

示例

请求示例

curl --location 'https://api.coze.cn/api/permission/oauth2/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InZZd2ZsdFR1OWZBbWtwWFhSdnR5UmREc3RONVMzZWNFcDFqVzB6dVQyRE****.eyJpc3MiOiIzMTAwMDAwMDAwMDIiLCJhdWQiOiJhcGkuY296ZS5jb20iLCJpYXQiOjE1MTYyMzkwMjIsImV4cCI6MTkxNjI1OTAyMiwianRpIjoiZmhqaGFsc2tqZmFkc2pld3F****.CuoiCCF-nHFyGmu2EKlwFoyd3uDyKQ3Drc1CrXQyMVySTzZlZd2M7zKWsziB3AktwbUZiRJlQ1HbghR05CW2YRHwKL4-dlJ4koR3onU7iQAO5DkPCaIxbAuTsQobtCAdkkZTg8gav9EnN1QN_1xq0w8BzuuhS7wCeY8UbaskkTK9GnO4eU9tEINmVw-2CrfB-kNbEHlEDwXfcrb4YPpkw3GhmuPShenNLObfSWS0CqIyakXL8qD5AgXLoB-SejAsRdzloSUInNXENJHfSVMkThxRhJy7yEjX3BmculC54fMKENRfLElBqwJyLLUjeRHsYnaru2ca4W8_yaPJ7F****' \
--data '{
    "duration_seconds": 86399,
    "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
}'

返回示例

{
    "access_token": "czs_RQOhsc7vmUzK4bNgb7hn4wqOgRBYAO6xvpFHNbnl6RiQJX3cSXSguIhFDzgy****",
    "expires_in": 1721135859
}

错误码