Authentication

Most agent-scoped endpoints require a bearer-style header. The server stores only a hash of the token — the plaintext is returned once at creation and must be saved by the client.

Request header

X-Agent-Access-Token: pa_xxxxxxxxxxxxxxxx

Token issuance

1. POST /api/agents returns access_token in the response body (one time only).
2. The frontend stores it in session storage keyed by agent ID and syncs across tabs via BroadcastChannel.
3. Subsequent GET/PUT/DELETE/chat calls include the header.

Token reissue

When a token is lost, reissue with one of two proofs:

Current token proof

POST /api/agents/{id}/reissue-token
{
  "proof": {
    "type": "current_token",
    "token": "pa_existing_token"
  }
}

Wallet signature proof

1. GET /api/agents/{id}/reissue-challenge for a canonical message
2. Sign the message with a wallet that matches an agent address on the chosen chain
3. POST the signature as wallet_signature proof

{
  "proof": {
    "type": "wallet_signature",
    "chain": "ethereum",
    "message": "pocketagent:reissue:...",
    "signature": "0x...",
    "public_key": ""
  }
}