DOCS / API REFERENCE / SIGNED REQUESTS AND AGENT IDENTITY
Signed Requests and Agent Identity API
How STACK signs an agent's requests, and what a website can look up about an agent. The steps are in the Recognition by websites guide.
Signed requests
- GET /.well-known/http-message-signatures-directory - STACK's public key directory: the public keys of every account that has signed, under opaque thumbprints, signed by STACK's own key. It names no account, agent or customer.
- GET /v1/accounts/:id/signing-keys - the key in use and any retired key still published. The agent or the operator reads it.
- POST /v1/accounts/:id/signing-keys/rotate - a new key signs from now on; the old one stays published for two days. Owner or admin; an agent context gets 403.
- GET /v1/agent-identity?key_id=|site=|agent_id= - who an agent is, answered on request, with no credential: a statement STACK signs (the agent, whether it is active, suspended or closed, and two yes-or-no facts of its owner: identity verified, good standing, spend held) and the same facts as JSON. Never the Passport and nothing else of the owner; an agent that is unknown, closed, opening or switched off by its owner is one and the same 404. The agent's name is shown only if its owner chooses.
- GET /v1/agent-identity/agents/:agent_id/agent-card.json, mcp-server-card.json and http-message-signatures-directory - the agent's signed A2A card, MCP server card and own key directory, served by STACK, public.
- GET /v1/accounts/:id/identity and PUT /v1/accounts/:id/identity { enabled?, show_name? } - what that answer shows: whether it answers at all (on by default) and whether the name is shown (off by default). Owner or admin; an agent context gets 403.
A site that checks for AI agents reads a signature on the request, finds the key in a directory and decides from it. STACK signs what its proxy and its cloud browser send for the account's agent, with HTTP Message Signatures as the IETF Web Bot Auth drafts describe them (Ed25519, covering the authority, method and path, valid for five minutes, with a nonce), and names its directory in Signature-Agent. The browser signs the page and what the page asks its own site for, never a third party's request, which a custom header would turn into a preflight. Each account has its own key, held KMS-wrapped like every other secret STACK keeps for you. The Visa Trusted Agent Protocol is not supported.