{"openapi":"3.1.0","info":{"title":"Totem agent verification API","version":"2026-08-15","description":"Challenge-bound, one-time verification of a registered external AI agent's scoped credential."},"servers":[{"url":"https://totemlayer.com"}],"paths":{"/api/v1/challenges":{"post":{"operationId":"createAgentVerificationChallenge","summary":"Create a receiver-owned verification challenge","security":[{"bearerApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChallengeCreate"}}}},"responses":{"200":{"description":"Exact idempotent replay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChallengeResponse"}}}},"201":{"description":"Challenge created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChallengeResponse"}}}},"400":{"description":"Missing or invalid idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Invalid receiver key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Receiver key lacks authority","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Relationship, agent, or idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Agent verification handshake rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"description":"Seconds until the current handshake rate-limit window resets.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Limit":{"description":"Request limit for the exhausted bucket.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Remaining":{"description":"Requests remaining in the exhausted bucket.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds when the bucket resets.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v1/presentations":{"post":{"operationId":"createAgentPresentation","summary":"Create a short-lived presentation for one challenge","security":[{"presenterBearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresentationCreate"}}}},"responses":{"201":{"description":"Presentation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresentationResponse"}}}},"401":{"description":"Invalid presenter key or challenge nonce","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential is not presentable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Challenge or relationship state changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Challenge expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Agent verification handshake rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"description":"Seconds until the current handshake rate-limit window resets.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Limit":{"description":"Request limit for the exhausted bucket.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Remaining":{"description":"Requests remaining in the exhausted bucket.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds when the bucket resets.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v1/presentations/verify":{"post":{"operationId":"verifyAgentPresentation","summary":"Consume a presentation and verify agent authority once","security":[{"bearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresentationVerify"}}}},"responses":{"200":{"description":"Credential approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationDecision"}}}},"401":{"description":"Invalid proof or receiver key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Credential policy rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationDecision"}}}},"409":{"description":"Presentation was already consumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Presentation expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Agent verification handshake rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"description":"Seconds until the current handshake rate-limit window resets.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Limit":{"description":"Request limit for the exhausted bucket.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Remaining":{"description":"Requests remaining in the exhausted bucket.","schema":{"type":"integer","minimum":0}},"X-RateLimit-Reset":{"description":"Unix timestamp in seconds when the bucket resets.","schema":{"type":"integer","minimum":1}}}}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","description":"Agent-bound API key with credential.verify scope."},"presenterBearerApiKey":{"type":"http","scheme":"bearer","description":"Agent-bound API key with the sole credential.present scope."}},"schemas":{"ChallengeCreate":{"type":"object","additionalProperties":false,"required":["presenterAgentId","requestedAction","requestDigest"],"properties":{"presenterAgentId":{"type":"string"},"requestedAction":{"type":"string"},"requestDigest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"transactionAmount":{"type":"number","minimum":0,"multipleOf":0.01},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}},"ChallengeResponse":{"type":"object","required":["challenge","replayed"],"properties":{"challenge":{"$ref":"#/components/schemas/Challenge"},"replayed":{"type":"boolean"}}},"Challenge":{"type":"object","required":["id","nonce","recipientOrganizationId","issuerOrganizationId","verifierAgentId","presenterAgentId","environment","requestedAction","requestDigest","expiresAt"],"properties":{"id":{"type":"string"},"nonce":{"type":"string"},"recipientOrganizationId":{"type":"string"},"issuerOrganizationId":{"type":"string"},"verifierAgentId":{"type":"string"},"presenterAgentId":{"type":"string"},"environment":{"type":"string","enum":["SANDBOX","PRODUCTION"]},"requestedAction":{"type":"string"},"requestDigest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"transactionAmount":{"type":"number","minimum":0,"multipleOf":0.01},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"expiresAt":{"type":"string","format":"date-time"}}},"PresentationCreate":{"type":"object","additionalProperties":false,"required":["credentialId","challengeId","nonce"],"properties":{"credentialId":{"type":"string"},"challengeId":{"type":"string"},"nonce":{"type":"string"}}},"PresentationResponse":{"type":"object","required":["presentation"],"properties":{"presentation":{"type":"object","required":["challengeId","credentialId","token","expiresAt"],"properties":{"challengeId":{"type":"string"},"credentialId":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}},"PresentationVerify":{"type":"object","additionalProperties":false,"required":["challengeId","presentation"],"properties":{"challengeId":{"type":"string"},"presentation":{"type":"string"}}},"VerificationDecision":{"type":"object","required":["verified","result","requestId","evidence"],"properties":{"verified":{"type":"boolean"},"result":{"type":"string","enum":["APPROVED","REJECTED","ERROR"]},"reasonCode":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"organization":{"type":"object"},"agent":{"type":"object"},"authorization":{"type":"object"},"evidence":{"type":"object","required":["challengeId","presentationJti","credentialId","requestDigest","verifiedAt"],"properties":{"challengeId":{"type":"string"},"presentationJti":{"type":"string"},"credentialId":{"type":"string"},"requestDigest":{"type":"string","pattern":"^[0-9a-f]{64}$"},"verifiedAt":{"type":"string","format":"date-time"}}}}},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}