Skip to main content
The Approvals API lets human reviewers preview a pending procurement deal and submit a binding approve-or-reject decision — all through a single cryptographically signed token embedded in an email link. Tavryn generates these tokens automatically whenever a negotiation outcome exceeds your policy threshold for human sign-off. The token encodes the contract, business, and action intent; you never need to log in to a dashboard to act on a deal.

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...0f88
Key security properties:
GET is preview only. POST executes the decision. Calling GET /api/approve/{token} reads deal terms without side effects. Calling POST /api/approve/{token} irreversibly consumes the token and records the approval or rejection in the audit log. Never POST to preview — you cannot undo a consumed token.

GET /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 parameters
string
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.
Response fields
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
Example request
Example response
Error responses

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 a 400 and leaves the token unconsumed.
This endpoint is irreversible. Once a token is consumed and the decision is recorded, neither the token nor the approval status can be rolled back through the API. Rejections are recorded in agent memory and influence future negotiation behavior for the same vendor.
Path parameters
string
required
The signed HMAC approval token to consume.
Request body
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".
Response fields
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.
Example request — approve
Example response — approve
Example request — reject
Example response — reject
Error responses

GET /api/approvals/count

Returns the number of approvals currently in pending 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.
Response fields
number
Total number of approvals with status "pending". Returns 0 on any error to prevent UI breakage.
Example request
Example response
This endpoint is safe to poll frequently. It always returns HTTP 200 even when no pending approvals exist or when a database error occurs — the count simply returns 0. Build your polling logic around the count value, not the status code.