API Reference

API Domain: https://open.palmoa.youtu.qq.com

Common Response Structure:

{
  "code": 0,            // 0 success, non-zero failure
  "message": "ok",
  "data": { ... }       // Business data, see each API for details
}

Authentication: All APIs below are business backend APIs. Create an app in the console to get an api_key, and include Authorization: Bearer <api_key> in the request header.

API Overview

Group	API	Method	Path
Binding	Exchange code for token	POST	/palm/openai/x/oauth/token
Verification	Create verification challenge	POST	/palm/openai/x/oauth/verify/challenges/create
Verification	Query verification status	POST	/palm/openai/x/oauth/verify/challenges/query

1. Exchange Code for Token

POST /palm/openai/x/oauth/token · Business Backend (api_key)

Use the code + code_verifier obtained from the SDK binding flow to exchange for open_id and access_token. Also supports refreshing with refresh_token.

Request Parameters

Field	Type	Required	Description
GrantType	string	Yes	authorization_code or refresh_token
Code	string	Conditional	Authorization code, required when GrantType=authorization_code
CodeVerifier	string	Conditional	PKCE verifier original value, required when GrantType=authorization_code
RefreshToken	string	Conditional	Refresh token, required when GrantType=refresh_token

Response data

Field	Type	Description
AccessToken	string	Access token
OpenId	string	Unique user identifier under this app
RefreshToken	string	Refresh token
TokenType	string	Always Bearer
ExpiresIn	int64	access_token validity period (seconds)

2. Create Verification Challenge

POST /palm/openai/x/oauth/verify/challenges/create · Business Backend (api_key)

Initiate verification for a user's sensitive operation. The operation is only released after the user confirms via palm scan on the PalmxApp.

Request Parameters

Field	Type	Required	Description
ChallengeId	string	Yes	UUID v4 generated by your business, idempotency key
OpenId	string	Yes	User's open_id (obtained during binding)
Action	string	Yes	Business action identifier, e.g. withdraw
ActionDetail	string	Yes	Business detail JSON, ≤512B, displayed to the user

Response data

Field	Type	Description
ExpiresAt	int64	Verification expiration timestamp (seconds)
Status	string	Initially pending; returns current status on idempotent hit

Idempotency: Re-submitting the same ChallengeId returns the existing status without creating a new verification.

3. Query Verification Status

POST /palm/openai/x/oauth/verify/challenges/query · Business Backend (api_key)

Short-poll the verification result. When approved, returns an Assertion JWT once.

Request Parameters

Field	Type	Required	Description
ChallengeId	string	Yes	The challenge_id from creation

Response data

Field	Type	Description
Status	string	pending / approved / denied / expired
AssertionJwt	string	One-time verification credential returned when approved

Status Reference

Status	Meaning	Business Action
pending	Waiting for user confirmation	Continue polling (recommended 2s)
approved	User confirmed	Release the operation
denied	User rejected	Deny the operation
expired	Timed out without response	Notify timeout, allow retry