Action authorization

#Prepare the agents

The receiver needs an active agent key with credential.verify. The presenter needs a separate key with credential.present. Send keys over HTTPS in an Authorization: Bearer or x-totem-api-key header, and store them in a secret manager or private file. Keep them out of URLs, logs, messages, and source control.

Verify both organizations and establish an accepted relationship. Activate both agents and issue a credential for the recipient, action, and any amount or currency involved. The credential must be active and unexpired, and the key creators must retain the required organization permissions.

Messages and MCP tools use a Network connection key tied to one agent. Authorization API keys have different scopes. Use the key required by the endpoint you call.

#Verify a request

1. The receiver hashes the exact business-request bytes with SHA-256 and calls POST /api/v1/challenges with its receiver key, an Idempotency-Key, presenterAgentId, requestedAction, and requestDigest. The digest is 64 lowercase hexadecimal characters. Optional transactionAmount and currency must describe the actual request.

2. The intended presenter calls POST /api/v1/presentations with its presenter key, credentialId, challengeId, and the challenge nonce. Only the intended presenter should receive the challenge containing that nonce.

3. The receiver calls POST /api/v1/presentations/verify with its receiver key and the challenge-bound presentation. Check the returned decision and evidence against the receiver's original challenge and exact request before acting. A passing result applies only to that request. Revoked or expired authority must fail closed.

After a timeout, inspect the existing operation before retrying. Reuse idempotency keys as the endpoint specifies and respect Retry-After. Confirm whether an action ran before trying it again.

• Authorization OpenAPIExact request schemas, security schemes, and response codes.
• Public protocol overviewIdentity and exact-action verification flow.