接口文档

接口域名： https://open.palmoa.youtu.qq.com

通用响应结构：

{
  "code": 0,            // 0 成功，非 0 失败
  "message": "ok",
  "data": { ... }       // 业务数据，见各接口
}

鉴权方式： 以下均为业务方后端接口，需在控制台创建应用拿到 api_key，请求头带 Authorization: Bearer <api_key>。

接口一览

分组	接口	Method	Path
绑定	授权码换 token	POST	/palm/openai/x/oauth/token
核验	发起核验 challenge	POST	/palm/openai/x/oauth/verify/challenges/create
核验	查询核验状态	POST	/palm/openai/x/oauth/verify/challenges/query

1. 授权码换 token

POST /palm/openai/x/oauth/token · 业务方后端（api_key）

用 SDK 绑定流程拿到的 code + code_verifier 换取 open_id 与 access_token；也支持用 refresh_token 刷新。

请求参数

字段	类型	必填	说明
GrantType	string	是	authorization_code 或 refresh_token
Code	string	条件	授权码，GrantType=authorization_code 时必填
CodeVerifier	string	条件	PKCE 验证码原文，GrantType=authorization_code 时必填
RefreshToken	string	条件	刷新令牌，GrantType=refresh_token 时必填

响应 data

字段	类型	说明
AccessToken	string	访问令牌
OpenId	string	用户在该应用下的唯一标识
RefreshToken	string	刷新令牌
TokenType	string	固定 Bearer
ExpiresIn	int64	access_token 有效期（秒）

2. 发起核验 challenge

POST /palm/openai/x/oauth/verify/challenges/create · 业务方后端（api_key）

对用户的敏感操作发起核验，用户在 PalmxApp 刷掌确认后方可放行。

请求参数

字段	类型	必填	说明
ChallengeId	string	是	业务方生成的 UUID v4，幂等键
OpenId	string	是	用户的 open_id（绑定时获取）
Action	string	是	业务动作标识，如 withdraw
ActionDetail	string	是	业务详情 JSON，≤512B，会展示给用户

响应 data

字段	类型	说明
ExpiresAt	int64	核验过期时间戳（秒）
Status	string	初始 pending；幂等命中时返回当前状态

幂等：同一 ChallengeId 重复提交返回已有状态，不创建新核验。

3. 查询核验状态

POST /palm/openai/x/oauth/verify/challenges/query · 业务方后端（api_key）

短轮询核验结果，approved 时一次性返回 Assertion JWT。

请求参数

字段	类型	必填	说明
ChallengeId	string	是	发起时的 challenge_id

响应 data

字段	类型	说明
Status	string	pending / approved / denied / expired
AssertionJwt	string	approved 时一次性返回的核验凭证

状态说明

Status	含义	业务方动作
pending	等待用户确认	继续轮询（建议 2s）
approved	用户已确认	放行操作
denied	用户已拒绝	拒绝操作
expired	超时未响应	提示超时，可重试