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

# Flight Booking

> Next step after Get Started: z-tenant-flight lets your organisation agent search and book flights through the Duffel API without seeing who is flying. Adds outbound HTTP, a sealed API key, per-host egress and profile placeholders. Needs a Duffel test token.

> [!NOTE]
>
> **At a glance**
>
> * **What it does:** your agent searches and books flights for a customer through the Duffel API; it only ever sees offers and a booking reference.
> * **What it adds to your Get Started setup:** calls to an outside API, an API key sealed in the enclave, a grant that allows exactly one host, and `{{profile.*}}` placeholders. Same key, same organisation agent, a new contract `z:<tid>:flight` next to your `vault`.
> * **What you need:** your Get Started `.env` (`T3N_API_KEY`, `AGENT_DID`, `AGENT_API_KEY`), a free Duffel **test** token, and test credits: registering it costs about as much as registering your `vault` did, and your agent needs at least 300 credits: the walkthrough uses up the 5 from Get Started, one search costs more than 5, and 100 covered exactly one search and one booking. The passenger's passport comes from the Private Doc Scanner or a JSON file the customer fills in.
> * **Build ideas:** hotels, rail or car hire through another API; the customer approves before the agent pays; per-agent spend limits.
> * **Sample repo:** [Terminal-3/z-tenant-flight](https://github.com/Terminal-3/z-tenant-flight)

[`z-tenant-flight`](https://github.com/Terminal-3/z-tenant-flight) is a contract that books flights through the [Duffel](https://duffel.com) API in test mode. Your agent searches and picks an offer. The customer's name, contact details and passport go from inside the enclave to Duffel, and the agent only gets back a booking reference.

It's the natural next step after the [walkthrough vault](https://docs.terminal3.io/developers/adk/get-started/walkthrough/write-contract.md), because it adds everything the vault deliberately leaves out: calls to an outside API.

| New compared with the vault | How |
| - | - |
| Outbound HTTP | Imports `http` (search) and `http-with-placeholders` (booking), so it runs in the `tenant-http-placeholders` world |
| A sealed API key | Your Duffel test token lives in `z:<tid>:secrets`; only the contract reads it ([Seed an API key](https://docs.terminal3.io/developers/adk/tips/seed-api-key.md)) |
| Per-host egress | The grant to your agent lists `api.duffel.com` in `allowed_hosts`; nothing else is reachable ([Outbound HTTP](https://docs.terminal3.io/developers/adk/tips/outbound-http-auth-by-user.md)) |
| Profile placeholders | Name and email are `{{profile.*}}` markers the node fills from the customer's T3N profile, so they never enter the contract ([Placeholders](https://docs.terminal3.io/developers/adk/tips/placeholders-outbound-calls.md)) |

## How it builds on your setup

Same key, same tenant, same organisation agent: the contract registers as `z:<tid>:flight` next to your `vault`, and you grant your agent `search-offers` and `book-offer` on it.

## Where the passenger's details come from

| Duffel needs | Comes from |
| - | - |
| Name, email | The customer's **T3N profile**, through `{{profile.*}}` placeholders |
| Title, phone number | The customer's **traveller record**, saved by the customer with `save-traveller` (refused for an agent) |
| Passport, including date of birth and sex | **Recommended:** a passport the customer scanned with the [Private Doc Scanner](https://docs.terminal3.io/developers/adk/use-cases/private-doc-scanner.md). **Or** entered in their traveller record |

The T3N profile holds only name and email, so the customer supplies the rest. The contract refuses an expired passport, and a scanned one whose details failed the scanner's checks or were edited by hand.

### Recommended: scan the passport

Scan it with the [Private Doc Scanner](https://docs.terminal3.io/developers/adk/use-cases/private-doc-scanner.md), signed in with the same Terminal 3 account, so its vault is in your tenant. Run the setup below as `npm run flight -- setup --with-scanner` (npm needs the `--` to pass the flag through), save a traveller record with just title and phone, and pass the scanner's reference as `scanner_request_id` when booking. Nobody types the passport number, and only fields the scanner verified are accepted. If setup says no vault was found but you already have one, it was set up before the scanner recorded contract ids: run `npx tsx scripts/setup-vault.ts --reregister` in the scanner's `starter/` folder, then run setup again.

### Or enter it yourself

The customer types their details into a JSON file and seals it to the contract. A traveller record with a passport (fictional values; field formats are in the [README](https://github.com/Terminal-3/z-tenant-flight#or-enter-the-passport-yourself)):

```json theme={null}
{
  "title": "ms",
  "phone_number": "+442071234567",
  "passport": {
    "number": "000000000",
    "issuing_country": "GB",
    "expires_on": "2031-04-11",
    "date_of_birth": "1990-04-12",
    "sex": "F"
  }
}
```

This is sample seed data you can seal as-is to try the flow. For real details, copy it to `starter/my-traveller.json` (git-ignored), edit it **yourself in your editor rather than through an AI assistant**, seal it with `npm run flight save-traveller my-traveller.json`, then **delete the file**. The sealed copy is the one the contract uses, and a file left on disk is one an assistant working in the folder could read.

## Run it

You need your Get Started setup (`T3N_API_KEY`, plus `AGENT_DID` and `AGENT_API_KEY` from [Create Your Organisation](https://docs.terminal3.io/developers/adk/get-started/create-organisation.md)) and a Duffel test token (`duffel_test_…`). The repository's `starter/` script does each step:

```bash theme={null}
git clone https://github.com/Terminal-3/z-tenant-flight.git && cd z-tenant-flight
cargo build --release
cd starter && npm install && cp .env.example .env   # fill in .env in your editor
npm run flight setup                       # register z:<tid>:flight, create its maps, seal the Duffel key
npm run flight save-traveller              # as the customer (or: save-traveller ../examples/traveller-scanner.json)
npm run flight grant                       # your agent: search-offers + book-offer, egress api.duffel.com
npm run flight fund-agent                  # 300 credits for your agent, from your own balance
npm run flight search LHR JFK 2026-12-15   # as the agent
npm run flight book <offer_id> <passenger_id> <total_amount> <total_currency>
```

The agent's booking input carries no personal data, only the offer: `{ offer_id, passenger_id, total_amount, total_currency }`. It gets back `{ id, pnr, status }`.

## Ideas to build on it

* **Hotels, rail or car hire**: the same shape with a different API and `allowed_hosts`.
* **Approval before paying**: have the agent search, and the customer confirm, before `book-offer` runs.
* **Spend limits**: check a per-agent budget in your own map before booking.


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