Navan Reference Architecture
Apps & Automationnavan-reference-architectureNavan Reference Architecture is an Agent Skill for apps & automation published in the jeremylongshore/claude-code-plugins-plus-skills repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when designing a production Navan API integration architecture — API gateway, token management, data sync pipelines, ERP connectors, and monitoring stack. Trigger with "navan reference architecture" or "navan integration architecture".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/plugins/saas-packs/navan-pack/skills/navan-reference-architecture/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/navan-reference-architecture, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Navan Reference Architecture
Overview
Production-grade architecture for Navan API integrations. Navan provides raw REST endpoints with OAuth 2.0 — no SDK, no webhooks, no sandbox. This architecture handles those constraints with five purpose-built layers.
Prerequisites
- Navan API credentials from Admin > Travel admin > Settings > Integrations
- Cloud infrastructure (AWS, GCP, or Azure) for hosting integration services
- Data warehouse for BOOKING and TRANSACTION tables
- Understanding of OAuth 2.0 client credentials flow
Instructions
Architecture Overview
┌──────────────────────────────────────────────────────────────────┐
│ CONSUMERS │
│ Travel Dashboard │ Expense Reports │ Finance System │
└────────┬────────────┴────────┬──────────┴────────┬───────────────┘
│ │ │
┌────────▼─────────────────────▼────────────────────▼───────────────┐
│ LAYER 1: API GATEWAY │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────┐ │
│ │ Rate Limiter │ │ Request Log │ │ Circuit Breaker (5xx) │ │
│ └─────────────┘ └──────────────┘ └─────────────────────────┘ │
└────────┬─────────────────────────────────────────────────────────┘
│
┌────────▼─────────────────────────────────────────────────────────┐
│ LAYER 2: TOKEN MANAGEMENT SERVICE │
│ ┌──────────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ OAuth Client Cred │ │ Token Cache │ │ Auto-Refresh │ │
│ │ POST /ta-auth/ │ │ (Redis/KMS) │ │ (before expiry) │ │
│ └──────────────────┘ └──────────────┘ └────────────────────┘ │
└────────┬─────────────────────────────────────────────────────────┘
│
┌────────▼─────────────────────────────────────────────────────────┐
│ LAYER 3: NAVAN API CLIENT │
│ ┌───────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
│ │ /get_user_trips│ │ /get_users │ │ /get_admin_trips │ │
│ │ /get_invoices │ │ /get_itin_pdf│ │ /reauthenticate │ │
│ └───────────────┘ └──────────────┘ └────────────────────────┘ │
└────────┬────────────────────┬────────────────────────────────────┘
│ │
┌────────▼──────────┐ ┌──────▼─────────────────────────────────────┐
│ LAYER 4: DATA │ │ LAYER 5: MONITORING │
│ SYNC PIPELINE │ │ ┌──────────┐ ┌─────────┐ ┌────────────┐ │
│ ┌───────────────┐ │ │ │ API Call │ │ Error │ │ Token │ │
│ │ Fivetran / │ │ │ │ Metrics │ │ Alerts │ │ Expiry │ │
│ │ Airbyte / │ │ │ │ (volume, │ │ (PD/ │ │ Monitor │ │
│ │ Estuary │ │ │ │ latency)│ │ Slack) │ │ │ │
│ ├───────────────┤ │ │ └──────────┘ └─────────┘ └────────────┘ │
│ │ BOOKING table │ │ │ │
│ │ (weekly full) │ │ └─────────────────────────────────────────────┘
│ ├───────────────┤ │
│ │ TRANSACTION │ │
│ │ (incremental) │ │
│ ├───────────────┤ │
│ │ ERP Connector │ │
│ │ (SAP/NetSuite)│ │
│ └───────────────┘ │
└───────────────────┘
Layer 1 — API Gateway
The gateway provides rate limiting, request logging, and circuit breaking before any call reaches Navan.
# Example: test gateway → Navan connectivity
curl -s -w "connect: %{time_connect}s | ttfb: %{time_starttransfer}s | total: %{time_total}s\n" \
-o /dev/null "https://api.navan.com/ta-auth/oauth/token"
Key decisions:
- Rate limiter: Token bucket at 80% of Navan's observed rate limit to provide buffer
- Circuit breaker: Open after 5 consecutive 5xx responses; half-open after 60 seconds
- Request log: Structured JSON with correlation ID, endpoint, response code, and latency
Layer 2 — Token Management Service
Centralized OAuth lifecycle management. Navan uses client_credentials grant type via POST /ta-auth/oauth/token.
# Token acquisition
TOKEN_RESPONSE=$(curl -s -X POST "https://api.navan.com/ta-auth/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=$NAVAN_CLIENT_ID&client_secret=$NAVAN_CLIENT_SECRET")
TOKEN=$(echo "$TOKEN_RESPONSE" | jq -r '.access_token')
EXPIRES=$(echo "$TOKEN_RESPONSE" | jq -r '.expires_in')
echo "Token acquired, expires in: ${EXPIRES}s"
Design principles:
- Cache tokens in Redis or KMS-encrypted storage — never in application memory across restarts
- Refresh tokens proactively 5 minutes before expiry
- Support multi-tenant scenarios with per-tenant credential isolation
Layer 3 — Navan API Client
Thin wrapper around Navan's REST endpoints with consistent error handling:
| Endpoint | Method | Purpose | Data Table |
|---|---|---|---|
/ta-auth/oauth/token | POST | OAuth token acquisition | — |
/v1/bookings | GET | Booking records | BOOKING |
/v1/users | GET | Employee directory | — |
Layer 4 — Data Sync Pipeline
Navan has no push/webhook mechanism — all data sync is poll-based.
| Table | Sync Strategy | Frequency | Connector |
|---|---|---|---|
| BOOKING | Full refresh | Weekly | Fivetran, Airbyte, or Estuary |
| TRANSACTION | Incremental (by date range) | Daily/hourly | Fivetran, Airbyte, or custom |
Connector selection:
- Fivetran: Managed, pre-built Navan connector, minimal configuration
- Airbyte: Open-source, self-hosted option, custom connector support
- Estuary: Real-time CDC where available, hybrid approach
Layer 5 — Monitoring Stack
| Metric | Alert Threshold | Channel |
|---|---|---|
| API error rate | > 5% over 5 minutes | PagerDuty (P2) |
| Token refresh failure | Any failure | PagerDuty (P1) |
| API response latency | p95 > 5 seconds | Slack |
| Data sync staleness | BOOKING > 8 days old | Slack |
| Rate limit proximity | > 80% utilization | Slack |
Output
- Architecture diagram adapted to your cloud provider and tooling
- Component specifications for each of the five layers
- Technology recommendations based on existing infrastructure
- Data flow documentation for BOOKING and TRANSACTION pipelines
Error Handling
| Failure Mode | Architecture Response |
|---|---|
| Token expired | Layer 2 auto-refreshes; Layer 1 retries transparently |
| Rate limited (429) | Layer 1 queues requests; Layer 5 alerts on sustained throttling |
| API outage (5xx) | Layer 1 circuit breaker opens; consumers get cached data |
| Data sync gap | Layer 4 runs catch-up sync; Layer 5 alerts on staleness |
Examples
Validate the full stack end-to-end:
# End-to-end integration test
echo "1. Auth..." && \
TOKEN=$(curl -s -X POST "https://api.navan.com/ta-auth/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=$NAVAN_CLIENT_ID&client_secret=$NAVAN_CLIENT_SECRET" \
| jq -r '.access_token') && \
echo "2. Users..." && \
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.navan.com/v1/users" | jq '.data | length' && \
echo "3. Bookings..." && \
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.navan.com/v1/bookings?page=0&size=50" | jq '.data | length'
Resources
- Navan Integrations — Connector catalog and partner ecosystem
- Navan Security — Infrastructure details (AWS, TLS, AES/KMS)
- Navan Help Center — API documentation and support
Next Steps
- Use
navan-prod-checklistto validate each layer before launch - Use
navan-data-syncfor detailed data pipeline configuration - Use
navan-observabilityfor monitoring stack implementation details