Skip to main content

Identity Verification

Live Demo

Try Identity Verification

Call verify/device to fetch the public key and verify the Agent registration status.

1
Enter DeviceId & OpenId
2
Fetch pubkey (verify/device)
3
View registration status

⚡ Sandbox demo — no data persisted.

After authorization is complete, the Agent signs every business API request to prove "this is still the same Agent."

Agent Side: Sign the Request​

Canonical string:

canonical = "palmauth-agent-req-v1"   + "\n"
          + device_id                 + "\n"
          + method                    + "\n"   // HTTP method, uppercase, e.g., POST
          + path                      + "\n"   // Business API path
          + sha256_hex(body_bytes)    + "\n"   // sha256 hex of raw request body bytes
          + timestamp_ms              + "\n"
          + nonce                                // Random string, one-time use
signature = Ed25519_sign(privkey, canonical)

The Agent sends device_id / timestamp / nonce / signature along with the request (in headers or parameters, as agreed with the business).

The domain prefix palmauth-agent-req-v1 differs from the registration string clawkey-register- to prevent cross-context replay.

Business Side: Two Verification Methods​

Method A (Recommended) · Fetch Public Key Cache + Local Verification​

The business fetches the public key once by (device_id, open_id) and caches it (TTL ≤15min). Subsequent requests are verified locally on the hot path, without depending on online API availability.

POST /palm/openai/x/agent/verify/device
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "DeviceId": "trader-001",
  "OpenId":   "u_a1b2c3..."     // Optional but strongly recommended: verify the device is bound to this person
}

Response:

{
  "code": 0,
  "data": {
    "Registered":  true,
    "DeviceId":    "trader-001",
    "OwnerOpenId": "u_a1b2c3...",
    "PubkeyDer":   "MCowBQYDK2VwAyEA...",   // base64(SPKI DER), cache for local verification
    "CreatedAt":   1717488000
  }
}

After obtaining PubkeyDer, the business locally: recalculates sha256_hex using the same raw body bytes received, reconstructs the canonical string, performs ed25519.Verify + checks timestamp ±5min + (device_id, timestamp, nonce) dedup.

Revocation delay = cache TTL. After a real person revokes, the cache must expire before the backend detects Registered=false. For faster revocation, shorten the TTL or use Method B for critical requests.

Method B · Online Signature Verification​

Forward the entire signature to Palm for online verification:

POST /palm/openai/x/agent/verify/signature
Authorization: Bearer <api_key>
Content-Type: application/json

{
  "DeviceId":  "trader-001",
  "PubkeyDer": "MCowBQYDK2VwAyEA...",
  "Message":   "<canonical string>",
  "Signature": "...",                 // base64
  "Timestamp": 1717488000000,
  "Nonce":     "random-once"          // Optional, anti-replay
}

Response:

{
  "code": 0,
  "data": {
    "Verified":    true,          // Whether the signature is valid
    "Registered":  true,          // Whether still bound to a real person (false if deactivated/revoked)
    "DeviceId":    "trader-001",
    "OwnerOpenId": "u_a1b2c3..."
  }
}

Verified is determined by cryptographic verification; Registered is independently determined by DB status — even if the signature is valid, a revoked Agent will have Registered=false, and the business should reject it accordingly.