Verification protocol

#Establish the principals

For this standalone authorization flow, both organizations must be verified, connected by an active relationship, and represented by active registered agents. The presenter needs an active recipient-bound credential for the requested action and any applicable amount or currency.

Use separate presenter and receiver keys with credential.present and credential.verify scopes. Network message connection keys have a different purpose; use the scoped key required by the endpoint.

Pin the expected HTTPS origin and protocol version. Each deployment publishes its discovery document and OpenAPI 3.1 contract so the integration can inspect the available endpoints and exact request schemas.

• Protocol discovery documentMachine-readable endpoint configuration and protocol metadata.
• Authorization OpenAPIRequest schemas, security schemes, and response codes.

#Challenge present and verify

The receiver hashes the exact business-request bytes with SHA-256, then creates a challenge with the intended presenter agent, action, request digest, and idempotency key. Totem returns a nonce and a five-minute challenge.

The named presenter authenticates and supplies its credential, challenge, and nonce to create a signed presentation with a maximum lifetime of one minute.

The receiver submits the presentation for verification. Totem locks the relevant state, consumes the proof once, and rechecks identity, relationship, keys, scope, limits, expiry, and revocation.

Before acting, the receiver checks the complete approval evidence against its original challenge, expected participants, and a fresh digest of its own request bytes. It applies its own business policy and executes only the request that was verified.

Receiver:  POST /api/v1/challenges
Presenter: POST /api/v1/presentations
Receiver:  POST /api/v1/presentations/verify

• Integrate action authorizationCredential preparation, request fields, and receiver checks.

#Handle failures and uncertain outcomes

Authentication failures return 401. Policy rejections return 403 with a structured reason. Conflicts and consumed state return 409, expiry returns 410, and rate limits return 429 with retry information. Network errors, timeouts, malformed JSON, server errors, and unknown reason codes do not count as approval.

After a timeout, inspect the existing operation before retrying. Reuse the logical operation's idempotency key as its endpoint specifies and respect Retry-After. Confirm whether a downstream action ran before attempting it again; missing evidence does not authorize a second effect.

Challenge and presentation artifacts contain short-lived bearer material. Keep keys, nonces, and temporary proof out of URLs, logs, metrics, shell arguments, and shared temporary directories. Prefer in-memory transfer and retain only the redacted evidence needed for audit.

#Compatibility

New integrations use the totemlayer package, the totem command, TOTEM_* environment variables, and x-totem-api-key. Existing agenttrust commands, headers, configuration routes, and protocol identifiers remain compatibility aliases for deployed integrations.

• CLI and SDKInstallation and integration options.

#Test the verification boundary

Exercise approval, replay, expiry, a wrong request digest, a wrong recipient, insufficient scope, and revocation before using the integration in production. Check both the verification decision and the receiving system's actual behavior.

• Security controls and limitsImplemented protections, receiver responsibilities, and disclosure.
• AI agent authenticationWorkload keys and challenge-bound proof used in the handshake.
• AI agent authorizationRecipient, request, scope, and current-state checks.
• API authentication guideA practical integration checklist for agent workloads.