Skip to main content

FAQ

Security Best Practices​

  1. Private key never leaves the device: The Agent's private key is its entire identity credential. Store it securely and never distribute or expose it.
  2. api_key stays on the business backend: Store in environment variables only, never distribute to the Agent client or frontend.
  3. Signatures bind to requests + anti-replay: The canonical string includes body_hash + timestamp + nonce. The business must verify the ±5min window and perform nonce deduplication.
  4. Identity ≠ single-operation authorization: High-risk operations must go through Step-up independently with real-time palm scanning. Do not use identity verification as a substitute.
  5. Assertion JWT six-step verification is mandatory: Every step is essential, especially the action_detail hash check and jti deduplication.
  6. Set cache TTL for public keys (≤15min): The worst-case revocation delay equals the TTL.

Frequently Asked Questions​

Q: Can the Agent directly obtain the real person's open_id?

A: No. The Agent only receives a one-time code. Only the business backend holding the api_key can call code/exchange to obtain the open_id. "Who the owner is" is only disclosed to the business.

Q: Can one real person authorize multiple Agents?

A: Yes. A single real person can authorize multiple Agents (multiple device_id) under the same app. Each has its own independent key pair, located by (open_id, device_id).

Q: Why doesn't the business API need to pass app_id?

A: The gateway injects oc_appid automatically from the api_key and enforces oc_appid == t_agent.app_id, ensuring you can only operate Agents under your own app.

Q: Can authorization be revoked? How long is it valid?

A: The real person can revoke authorization at any time in PalmxApp under "My Authorizations." The authorization duration is selected during confirmation (1d/3d/7d/30d, default 7d). After expiration, the binding becomes invalid.

Q: Can device_id be changed after registration?

A: No. device_id is the Agent's stable external identity and cannot be changed after registration. To change identity, register with a new device_id.

Q: Is Step-up mandatory?

A: It depends on business risk. Read-only / low-risk operations can use identity verification only (Phase 2). Transfers, withdrawals, deletions, and other high-risk operations must go through Step-up (Phase 3).