Token Security Model
Tavryn approval tokens are tamper-proof and single-use. Understanding how they work helps you integrate them safely into your approval workflows.Each token is structured as
{nonce}.{hmac_signature} where the HMAC is computed over the payload contractId:businessId:action:nonce:expiresAt using HMAC-SHA256. Any modification to the token structure renders it immediately invalid.string
required
The full approval token string in
{nonce}.{hmac_signature} format. Tokens are 40 hex characters (nonce) followed by a period and a 64-character hex HMAC digest. Example: a3f7...b2c1.e9d4...0f88GET /api/approve/
Preview the deal terms associated with an approval token. This endpoint is read-only and requires no authentication — the signed token itself is the credential. Use it to render an approval UI before the reviewer commits. Path parametersstring
required
The signed HMAC approval token. Passing
demo, sample, or any token prefixed with demo returns a static sample Datadog deal for UI testing without touching the database.string
The token’s UUID as stored in the database.
string
ISO 8601 timestamp indicating when this token expires and can no longer be redeemed.
string
The action this token was generated for. One of
approve, reject, or decide.object
POST /api/approve/
Submit a binding approve-or-reject decision for a pending deal. This endpoint consumes the token — it can only be called once per token. On approval, Tavryn re-evaluates your policy server-side before authorizing escrow funding; a policy violation at this stage returns a400 and leaves the token unconsumed.
Path parameters
string
required
The signed HMAC approval token to consume.
string
required
The reviewer’s decision. Must be exactly
"approve" or "reject".string
Optional plain-text explanation for the decision (max 1,000 characters). For rejections, Tavryn stores this in agent override memory to tune future negotiations with the same vendor.
string
Optional structured reason code for rejections (max 100 characters). Examples:
"rate_too_high", "wrong_vendor", "budget_freeze".string
The resulting approval status:
"approved" or "rejected".string
ISO 8601 timestamp of when the decision was recorded.
string
Human-readable confirmation message. Approvals confirm escrow authorization; rejections confirm feedback was recorded in agent memory.
GET /api/approvals/count
Returns the number of approvals currently inpending status. Use this endpoint to drive notification badges, dashboard counters, or polling loops that alert reviewers when new deals are waiting.
Query parameters
string
UUID of the business to scope the count to. If omitted, the count includes all pending approvals across every business in your account.
number
Total number of approvals with status
"pending". Returns 0 on any error to prevent UI breakage.