Skip to main content

Palm Agent Integration Guide

Issue a "real-person claimed" identity credential to AI Agents, and ensure that every dangerous operation performed by the Agent requires the real person to verify with a palm scan.

Overview​

This document helps third-party businesses integrate their AI Agents with Palm, addressing two main concerns:

  1. Agent Identity — Allow an Agent (script / bot / automated process) to run as a "real person". After the real person scans their palm via PalmxApp, the Agent receives a pair of Ed25519 key-based "claim credentials", enabling the business to know "which user in my system is behind this Agent."

  2. Operation-level Step-up Verification — Identity verification does not mean the real person has approved this specific operation. When an Agent initiates a high-risk operation (transfer, withdrawal, deletion, etc.), the business calls the Step-up API to require the real person to scan their palm on PalmxApp. After confirmation, the business receives an Assertion JWT as the authorization credential.

Relationship with OAuth Integration: OAuth verifies "human users," while Agent verifies "AI representing a human." The two have independent API endpoints (/x/agent/* vs /x/oauth/*) and can be integrated separately.

Roles and Prerequisites​

RoleIdentity / AuthenticationResponsibilities
Agent Clientapp_id (public) + local Ed25519 private key self-signingGenerate keys, initiate registration, sign each business request
Business Backendapi_key (product_code='agent' app)Exchange for open_id, verify signatures, initiate Step-up
Real Person OwnerPalmxApp login sessionScan palm to confirm authorization, manage/revoke Agents

Prerequisites:

  1. Create an app with product_code='agent' in the Palm console to obtain app_id (public) and api_key (business backend secret, store in env-only, never distribute to the Agent client).
  2. Users must have previously logged in or bound their account using Palm in your system, meaning your system already has the open_id ↔ local account mapping. An Agent acts "on behalf of an existing account"; without this binding, authorization cannot proceed.

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

CallerGateway Prefix
Agent Client (without api_key)/palm/openai/x/agent/...
Business Backend (with api_key)/palm/openai/x/agent/..., with Authorization: Bearer <api_key>
PalmxApp (real person logged in)/palm/openconsole/x/agent/...

Business API requests do not need to pass app_id — the gateway injects it automatically from the api_key (oc_appid). The server locates the Agent using (oc_appid, device_id) and enforces that you can only operate Agents under your own app.

Full Chain Overview​

[Authorization Phase]
 ┌─ Agent Client ────────────────────────────────────────────────┐
 │ 1. Generate Ed25519 key pair locally (private key never leaves) │
 │ 2. Self-sign and call register/init → get registration_url + session_id│
 └────────────────────────────────────────────────────────────────┘
              │ Pass registration_url to the real person
              ↓
 ┌─ Real Person / PalmxApp ──────────────────────────────────────┐
 │ 3. Open url in browser → PalmxApp scans QR → palm scan + select duration │
 │    Server single transaction: t_agent=active + bind owner + generate code│
 └────────────────────────────────────────────────────────────────┘
              ↓
 ┌─ Agent Client ────────────────────────────────────────────────┐
 │ 4. Poll register/status with session_id → get status + one-time code│
 │    (receives a code, NOT open_id)                             │
 └────────────────────────────────────────────────────────────────┘
              │ Pass code to business
              ↓
 ┌─ Business Backend (api_key) ─────────────────────────────────┐
 │ 5. code/exchange → get (device_id, open_id)                   │
 │ 6. Look up local account binding with open_id: found → done; not → fail│
 └────────────────────────────────────────────────────────────────┘

[Each Business Request]
 7. Agent signs "canonical string (body_hash+ts+nonce)" with private key, sends device_id to business
 8. Business fetches public key by (open_id, device_id), caches it (TTL≤15min), verifies locally + checks ts + nonce dedup

[High-risk Operations — Must Require Real-time Palm Scan]
 9. Business calls stepup/create for high-risk actions → Real person scans palm on PalmxApp → Server signs Assertion JWT
10. Business polls stepup/query for JWT → verifies signature + recalculates action_detail_hash + jti dedup → executes

The integration is divided into three phases. Continue reading the following documents:

  1. Registration and Authorization — Agent registration and identity authorization
  2. Identity Verification — Request signing and signature verification
  3. High-risk Operation Verification — Step-up palm scan confirmation