---
title: The three calls
description: Register the organisation, create an identity, set what it may spend. Everything after that is a header on requests you already make.
canonical: https://tollrelay.com/docs
lastmod: 2026-09-15
---

# The three calls

Register the organisation, create an identity, set what it may spend. Everything after that is a header on requests you already make.

## Register the organisation

```http
POST https://api.trlay.dev/identity/orgs
{ "name": "Acme Research", "handle": "acme", "region": "eu", "email": "you@acme.example" }
```

One call, one verification. The organisation is the thing sellers trust; passes hang off it. The `region` is `eu` or `us`. It is chosen here and cannot be changed later.

## Issue a pass

```http
POST https://api.trlay.dev/identity/machines
{ "org": "org_eu_…", "label": "procurement-agent" }
```

One per agent, under the organisation. Each gets a signing key, returned once. Name it what your team calls the agent; receipts show it as `acme/procurement-agent`.

## Set a spending limit

```http
PUT https://api.trlay.dev/mandates/mid_eu_…
{ "usd_per_day": "50", "usd_per_call_max": "1", "sellers_allow": ["api.exa.ai", "api.firecrawl.dev"] }
```

Per day, per call, per seller. The API calls this a mandate. The pass carries it, so sellers can see the limit before they charge.

## Sign it off

```http
POST https://api.trlay.dev/mandates/mid_eu_…/versions
{ "constraints": [{ "type": "com.tollrelay.usd_per_day", "max_usd": "50" }] }
```

Propose a version, and a person who approves reads the constraints in words and signs or refuses on the dashboard. No agent key reaches that screen. A version that creates or widens what the agent may spend needs two signatures once the organisation is on the Business plan or above, and never the agent's own creator alone.

Issuing the signed credential from a completed signature is coming.

## Attach it to every request

The SDK signs and adds one header, `X-Trlay-Identity`. If the seller charges, the SDK checks the spending limit first, as a courtesy. The seller's check and the wallet enforce it.

Pushing that limit into the wallet you already use is coming.

## Approvals

A call that trips a rule on the spending limit, a first payment to a new seller or a cumulative cap, waits for a person instead of failing.

```http
POST https://api.trlay.dev/approvals
{ "mid": "mid_eu_…", "mandate_version": 3, "closed_mandate": "…", "seller": "api.exa.ai", "amount_usd": "1.500", "rail": "x402" }
```

A person reviews it on the dashboard and approves or refuses with a signed decision. The agent reads the item back for the outcome before it tries the call again.

## Read the history

Every checked call lands in your history: seller, amount, receipt. Export it for finance.

A signed proof of each order for an audit, per region, is coming.

On the other side, a seller runs a check to read the pass and the spending limit that remains. See [Verify](https://tollrelay.com/docs/verify).