> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Navan Integration: Travel and Expense Data for Agents
> Agents can read Navan bookings and expense transactions, and sync expense data back. The gateway injects and refreshes the client credentials token.
## Overview
OneCLI connects AI agents to Navan through the Navan API. Agents can read travel bookings and expense transactions, and write ERP sync status, GL codes, tax mappings, and custom field values back to Navan. The gateway injects credentials into requests to `api.navan.com`, so your agent never sees them.
Navan uses machine-to-machine OAuth 2.0 (the client credentials grant), not a browser sign-in. You create a Client ID and Secret Key in Navan, and OneCLI exchanges them for an access token. Tokens last 12 hours, and the gateway gets a new one automatically when the current one expires.
## Prerequisites
* A Navan account with **Administrator** permissions
* For expense endpoints: Navan must enable the **Expense API** for your company. Ask Navan support or your account team. Until it's enabled, expense requests return `403 Forbidden`. Booking endpoints work without it.
## Setup
Sign in to [Navan](https://app.navan.com), click the Navan logo in the top left, and select **Admin**.
* **1.** In the left menu, go to **Travel** > **Settings** > **Integrations**.
* **2.** In the **Navan API credentials** section, click **Create new**.
* **1.** Enter a **Description**, for example `OneCLI`. Leave **Allowed IP Addresses** empty.
* **2.** Select the scopes your agents need:
| Scope | Grants |
| - | - |
| **Booking: Read Only** | Read travel bookings |
| **Expense: Read Only** | Read expense transactions, receipts, and custom fields |
| **Expense: Write** | Update transactions, custom field options, GL codes, and tax mappings |
* **3.** Click **Create**.
* **1.** The **Client ID**. You'll paste it into OneCLI next.
* **2.** The **Secret Key**. Click **Copy key** to copy it on its own.
* **3.** Click **Save and Copy all** to copy the Description, Client ID, and Secret Key together.
Navan shows the Secret Key only once. Save it before you close the dialog. If you lose it, delete the credential and create a new one.
Open the OneCLI dashboard, go to **Connections**, find **Navan**, and click **Connect**.
* **1.** Paste the **Client ID** from Navan.
* **2.** Paste the **Secret Key** from Navan.
* **3.** Expand **Advanced** only if your company is hosted in Navan's EU region, and set **Region** to `eu`. Leave it empty for US.
* **4.** Click **Connect Navan**.
OneCLI exchanges the credentials for a token when you connect. If the credential is invalid or has no scopes selected, the connection fails with an error that explains why.
[Grant](/docs/guides/agent-access) the Navan connection to each agent that needs it.
### EU companies
Set **Region** to `eu` (under **Advanced** in the connect window) if your company is hosted in Navan's EU region. OneCLI then uses Navan's EU token endpoint and adds the `X-ta-region: EU` header to every request. Navan answers EU requests without that header with `500 Internal Server Error`, so your agent doesn't need to add the header itself.
## Make a request
Your agent calls the Navan API directly, without an `Authorization` header. The gateway adds it.
```bash theme={null}
curl "https://api.navan.com/v1/bookings?createdFrom=2026-09-01&createdTo=2026-09-30&page=0&size=20"
```
```json theme={null}
{
"data": [],
"page": {
"totalElements": 0,
"currentPage": 0,
"pageSize": 20,
"totalPages": 0
}
}
```
The bookings endpoint requires a complete date range: `createdFrom`/`createdTo`, `updatedFrom`/`updatedTo`, or `startDateFrom`/`startDateTo`. Without one, Navan returns `400 Bad Request`.
## What agents can do
| Area | Endpoints | Access |
| - | - | - |
| **Bookings** | `GET /v1/bookings` | Read |
| **Card transactions** | `GET /v1/expense/card-transactions`, `/connect-transactions` | Read |
| **Other transactions** | `GET /v1/expense/manual-transactions`, `/repayments`, `/fees`, `/adjustments`, `/daily-rebates`, `/disputes`, `/statement-payments` | Read |
| **Any transaction type** | `GET /v1/expense/transactions`, `/transactions/{id}` | Read |
| **Receipts** | `GET /v1/expense/transactions/receipts`, `/transactions/{id}/receipt` | Read |
| **Custom fields** | `GET /v1/expense/custom-fields`, `/custom-fields/{name}` | Read |
| **GL codes** | `GET /v1/expense/gl-codes`, `/gl-codes/{number}`, `/gl-code-settings` | Read |
| **Tax mappings** | `GET /v1/expense/tax-mappings`, `/tax-mappings/by-tax-code` | Read |
| **Update transactions** | `PATCH /v1/expense/transactions` | Write |
| **Custom field options** | `POST /v1/expense/custom-fields/{name}/options` | Write |
| **Manage GL codes** | `PUT`/`PATCH /v1/expense/gl-codes`, `PATCH /gl-code-settings`, `POST`/`DELETE /gl-code-exclusions` | Write |
| **Manage tax mappings** | `PUT`/`PATCH`/`POST`/`DELETE /v1/expense/tax-mappings` | Write |
For request parameters and response fields, see the [Navan Expense API reference](https://docs.navan.com/api/).
## Use cases
* Finance agents that sync expense transactions into an ERP and mark them as synced in Navan
* Reporting agents that pull card spend, fees, and rebates for a period
* Travel agents that list upcoming trips and their bookings
* Admin agents that keep custom field options and GL codes in sync with your ERP
## Troubleshooting
The Expense API isn't enabled for your company yet, or the credential lacks an Expense scope. Ask Navan support to enable the Expense API, and check the credential's scopes in **Travel** > **Settings** > **Integrations**.
The Client ID or Secret Key is wrong, or the region doesn't match your account. A US credential fails against the EU region and the other way around.
The credential was created without any scope selected. Delete it in Navan and create a new one with at least one scope.
The credential doesn't have the **Expense: Write** scope. Edit the credential in Navan to add it, then reconnect in OneCLI.
## Controlling access
Access is per agent: [grant](/docs/guides/agent-access) the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked. A read-only agent is a single grant. Organization [rules](/docs/guides/rules) add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches the Navan API.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.