> ## Documentation Index
> Fetch the complete documentation index at: https://tavryn.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Approval Tokens: Preview Deals and Submit Decisions

> Preview pending deal terms and submit a binding approve-or-reject decision via a signed, single-use token. Token expiry, security model, and error codes.

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.

> [!NOTE]
>
> 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.

**token** `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:**

| Property | Value |
| - | - |
| Signing algorithm | HMAC-SHA256 |
| Default expiry | **48 hours** from generation |
| Reuse | **Single-use** — consumed atomically on `POST` |
| Token hash storage | SHA-256 hash of the token (not the raw token) |

> [!WARNING]
>
> **`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/{token}

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**

**token** `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**

**token** `string`

The token's UUID as stored in the database.

**expiresAt** `string`

ISO 8601 timestamp indicating when this token expires and can no longer be redeemed.

**action** `string`

The action this token was generated for. One of `approve`, `reject`, or `decide`.

**contract** `object`

**contract fields**

**id** `string`

UUID of the contract being reviewed.

**service** `string`

Human-readable name of the SaaS or cloud service. Example: `"Datadog Cloud Monitoring"`.

**category** `string`

Spend category. One of `software`, `cloud`, `contractors`, `infrastructure`, `legal`, or `marketing`.

**baselinePrice** `number`

The current annual contract price (in USD) before Tavryn's negotiation.

**proposedPrice** `number`

The negotiated price Tavryn is recommending. This is the amount that will be committed if you approve.

**annualSavings** `number`

Calculated as `baselinePrice − proposedPrice`. Always ≥ 0.

**savingsPct** `number`

Savings as a percentage of the baseline price, rounded to the nearest integer.

**vendor** `object`

Vendor metadata including `name` and `is_simulated` flag.

**business** `object`

Business metadata including `id` and `name`.

**Example request**

```bash theme={null}
curl https://tavryn.network/api/approve/a3f7c2b1...e9d40f88...
```

**Example response**

```json theme={null}
{
  "token": "37448d59-445c-4e43-bc7e-aad1215986bd",
  "expiresAt": "2026-04-02T14:30:00.000Z",
  "action": "decide",
  "contract": {
    "id": "c9a1f820-1234-4d56-a789-bc3d0e001f22",
    "service": "Datadog Cloud Monitoring",
    "category": "cloud",
    "baselinePrice": 37200,
    "proposedPrice": 29760,
    "annualSavings": 7440,
    "savingsPct": 20,
    "vendor": {
      "name": "Datadog",
      "is_simulated": false
    },
    "business": {
      "id": "biz-uuid",
      "name": "Acme Corp"
    }
  }
}
```

**Error responses**

| Status | Condition |
| - | - |
| `400` | Token is malformed, missing, expired, or already redeemed. The error detail includes `used: true` for a consumed token and `expired: true` for a past-expiry token |

***

## POST /api/approve/{token}

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.

> [!WARNING]
>
> 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**

**token** `string` *required*

The signed HMAC approval token to consume.

**Request body**

**action** `string` *required*

The reviewer's decision. Must be exactly `"approve"` or `"reject"`.

**reason** `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.

**reasonCode** `string`

Optional structured reason code for rejections (max 100 characters). Examples: `"rate_too_high"`, `"wrong_vendor"`, `"budget_freeze"`.

**Response fields**

**status** `string`

The resulting approval status: `"approved"` or `"rejected"`.

**decidedAt** `string`

ISO 8601 timestamp of when the decision was recorded.

**message** `string`

Human-readable confirmation message. Approvals confirm escrow authorization; rejections confirm feedback was recorded in agent memory.

**Example request — approve**

```bash theme={null}
curl -X POST https://tavryn.network/api/approve/a3f7c2b1...e9d40f88... \
  -H "Content-Type: application/json" \
  -d '{ "action": "approve" }'
```

**Example response — approve**

```json theme={null}
{
  "status": "approved",
  "decidedAt": "2026-04-01T09:15:22.000Z",
  "message": "Contract successfully approved and authorized for escrow funding."
}
```

**Example request — reject**

```bash theme={null}
curl -X POST https://tavryn.network/api/approve/a3f7c2b1...e9d40f88... \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reject",
    "reason": "We already signed a multi-year deal last quarter.",
    "reasonCode": "already_contracted"
  }'
```

**Example response — reject**

```json theme={null}
{
  "status": "rejected",
  "decidedAt": "2026-04-01T09:17:05.000Z",
  "message": "Contract rejected. Decision feedback recorded in agent memory."
}
```

**Error responses**

| Status | Condition |
| - | - |
| `400` | Malformed JSON body |
| `400` | Invalid `action` value (must be `"approve"` or `"reject"`) |
| `400` | Token expired, not found, or already redeemed |
| `400` | Policy boundary violated on approve — token is not consumed in this case |

***

## 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**

**businessId** `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**

**count** `number`

Total number of approvals with status `"pending"`. Returns `0` on any error to prevent UI breakage.

**Example request**

```bash theme={null}
curl "https://tavryn.network/api/approvals/count?businessId=biz-uuid"
```

**Example response**

```json theme={null}
{
  "count": 3
}
```

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.