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，即非对称加密算法，一种基于 RSA（非对称加密算法）+ SHA256（安全哈希函数）的签名算法，该算法使用私钥进行签名，公钥进行验证。 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', '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 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 }