Navan package v1.0.0

An OAuth 2.0 access token for the Navan Expense API, held in the client's own secret manager. The stored material must be the complete Authorization header value (scheme included): 'Bearer', one separating space, then the access token — 'Bearer <token>'.

An external token process mints it with the client credentials grant: an admin creates API credentials (client_id and client_secret) in the Navan platform, and the process POSTs grant_type=client_credentials with the client_id and client_secret to https://app.navan.com/ta-auth/oauth/token (https://app-fra.navan.com/ta-auth/oauth/token for EU companies) and stores the returned access token; the client secret is itself secret material and stays with that external process.

Navan documents tokens as valid for 12 hours by default, so the external process must refresh on expiry — the executor must not attempt renewal itself; the API credentials can be rescoped or revoked in the Navan platform at any time, and an expired or revoked value fails closed. Do not pass an explicit scope parameter at token time: Navan documents that an explicit scope overrides and limits the token's permissions.

Least privilege: credentials are read-only by default — only the PATCH capability needs the Expense: Write scope, so a read-only deployment should not grant it, and a deployment that enables the update capability must accept exactly that one write scope. EU deployments must also send the X-ta-region=EU header on every request; that wiring is a pre-enablement review item.

Executor hygiene: the token must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must never appear in crash reports; the executor's memory, log and crash handling are otherwise the deployment's review.

Use Navan API credentials whose scopes cover only what these capabilities need; the pack does not create them. This pack registers only the Navan Expense API surface documented in the official developer portal: the retrieval endpoints under https://api.navan.com/v1/expense and the batch PATCH update on /v1/expense/transactions.

All reads are collection reads only — the single-transaction read (GET /v1/expense/transactions/{id}) and the single-transaction receipt endpoints exist in the API and are deliberately not registered, and every list call must carry a date filter (Navan rejects requests without one; windows are capped at 93 days).

The PATCH capability is registered as update at the minimum R2 tier: it changes accounting attributes on existing transactions (ERP sync status, GL codes, HR fields, custom field values) — it is request-accepted with per-transaction status in the response, and the reference's documented updatable field list for this PATCH (transaction id, ERP sync status — updates to SYNCED only — plus external ERP reference fields, GL code number and name, the HR fields department/region/subsidiary/cost_center, and custom field values) contains no approval-status field, so the update cannot change approval status and is not an approval action.

Documented exclusions, framed as what this pack does not register: travel bookings — the official token example shows a bookings:read scope and Navan operates a Booking Data API, but its endpoint reference is not part of the official documentation retrieved for this review, so this pack registers no bookings endpoint; users — no users endpoint appears in the retrieved official Expense API documentation; expense approval — the reviewed documentation describes no approve endpoint, and the PATCH update cannot set approval_status; receipts download redirects (the redirect target is a presigned URL on another host and AAES does not follow redirects); the hosted Navan MCP server (mcp.navan.com), a separate user-context surface; and every write other than the registered PATCH.

EU deployments: Navan documents that EU companies must send the X-ta-region=EU header on every request and use the EU token endpoint — the deployment must wire that header before enabling against an EU tenant.

Transaction data may take up to 4 hours to appear in GET results after an update. AAES has not been certified by Navan; the endpoints here are configuration to review and test; the vendor has not endorsed it.

Source annotation for https://docs.navan.com/api/ (retrieved 2026-09-21): Authentication: OAuth 2.0 client-credentials grant, 12-hour default token validity, Expense: Write scope requirement for PATCH, explicit-scope override warning Source annotation for https://docs.navan.com/api/ (retrieved 2026-09-21): section 1 'Retrieve Navan card transactions' (GET /v1/expense/card-transactions): required date filter, card-specific fields Source annotation for https://docs.navan.com/api/ (retrieved 2026-09-21): section 3 'Retrieve manual transactions' (GET /v1/expense/manual-transactions) Source annotation for https://docs.navan.com/api/ (retrieved 2026-09-21): section 9 'Generic API — retrieve all transaction types' (GET /v1/expense/transactions): required type array and date filter, _type discriminator Source annotation for https://docs.navan.com/api/ (retrieved 2026-09-21): section 11c 'Get receipt links by date filter' (GET /v1/expense/transactions/receipts): required type[] and date parameter, presigned URLs not to be cached Source annotation for https://docs.navan.com/api/ (retrieved 2026-09-21): section 'Update transactions endpoint (batch update with PATCH)' (PATCH /v1/expense/transactions): updatable field groups contain no approval-status field, per-transaction results[].status, 4-hour GET visibility delay