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

# Sync Navan Bookings and Expenses With AI Agents

> Let agents read Navan bookings and expenses and sync ERP data back. The gateway exchanges and refreshes client credentials, so agents never see them.

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

## What you will set up

* Navan API credentials (Client ID and Secret Key) with the scopes you need
* A connection that gets and refreshes 12-hour access tokens
* Per-agent, per-tool access to bookings and expenses

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

**1. Create API credentials in Navan**

Sign in to [Navan](https://app.navan.com), click the Navan logo in the top left, and select **Admin**.

![Navan Admin Integrations page with the Integrations menu item and the Create new button in the Navan API credentials section highlighted.](https://mintcdn.com/chartdbinc/4QUhmBQbRL1cjHvq/images/integrations/navan/01-integrations.png?fit=max\&auto=format\&n=4QUhmBQbRL1cjHvq\&q=85\&s=a13d862ee6494bc96f3353ca993bc9e1)

Open Integrations and start a new API credential.

* **1.** In the left menu, go to **Travel** > **Settings** > **Integrations**.
* **2.** In the **Navan API credentials** section, click **Create new**.

![Navan Create new API credential dialog with the Description field, the three scope checkboxes, and the Create button highlighted.](https://mintcdn.com/chartdbinc/4QUhmBQbRL1cjHvq/images/integrations/navan/02-create-credential.png?fit=max\&auto=format\&n=4QUhmBQbRL1cjHvq\&q=85\&s=ca231a21fcf291afce360ac377cfe281)

Name the credential and select the scopes your agents need.

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

![Navan API credential created dialog with the Client ID and Secret Key fields (values hidden) and the Save and Copy all button highlighted.](https://mintcdn.com/chartdbinc/4QUhmBQbRL1cjHvq/images/integrations/navan/03-credential-created.png?fit=max\&auto=format\&n=4QUhmBQbRL1cjHvq\&q=85\&s=3b9448df18c94dc8ca64d19f8a4fbad5)

Copy the Client ID and Secret Key before you close the dialog.

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

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

**2. Connect in OneCLI**

Open the OneCLI dashboard, go to **Connections**, find **Navan**, and click **Connect**.

![OneCLI connect window for Navan with the Client ID, Secret Key, and Region fields and the Connect Navan button highlighted. Advanced is expanded.](https://mintcdn.com/chartdbinc/4QUhmBQbRL1cjHvq/images/integrations/navan/04-onecli-connect.png?fit=max\&auto=format\&n=4QUhmBQbRL1cjHvq\&q=85\&s=e2e013dafb13f153ff0e5a38d9c60106)

Enter the Navan credential in OneCLI. Region is under Advanced.

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

**3. Grant the connection to an agent**

[Grant](https://onecli.sh/docs/guides/agent-access.md) the Navan connection to each agent that needs it.

> [accordion] Optional: company hosted in Navan's EU region
>
> **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

> [accordion] Expense requests return 403 Forbidden
>
> 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**.

> [accordion] Connecting fails with 401
>
> 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.

> [accordion] Connecting fails with "no scopes"
>
> The credential was created without any scope selected. Delete it in Navan and create a new one with at least one scope.

> [accordion] Writes return 403 Forbidden
>
> 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](https://onecli.sh/docs/guides/agent-access.md) 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](https://onecli.sh/docs/guides/rules.md) 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.

## FAQ

> [accordion] How do I rotate Navan credentials?
>
> Create a new credential in Navan, then update it in the Navan connection in OneCLI. Agents pick it up automatically. Then delete the old credential in Navan.

> [accordion] How do I keep Navan credentials out of the agent's context?
>
> Store them in OneCLI. The gateway exchanges them for tokens and injects them at the proxy. See [How it works](https://onecli.sh/docs/how-it-works.md).

> [accordion] I lost the Secret Key. What now?
>
> Navan shows it only once. Delete the credential and create a new one.


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