Set up a local development environment for Navan API integrations with token caching and request logging.
Use when starting a new Navan project or debugging API issues locally.
Trigger with "navan local dev", "navan dev setup", "navan local dev loop", "navan dev environment".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Set up a local development environment for Navan API integrations with token caching and request logging.
Use when starting a new Navan project or debugging API issues locally.
Trigger with "navan local dev", "navan dev setup", "navan local dev loop", "navan dev environment".
allowed-tools
Read, Write, Edit, Bash(npm:*), Grep
version
1.7.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","navan","travel"]
compatibility
Designed for Claude Code
Navan Local Dev Loop
Overview
Configure a local development environment for Navan API integrations with token caching, request logging, and mock fixtures. Navan has no sandbox โ all API calls hit production, making a structured local setup essential.
Purpose: Establish a safe local dev workflow that minimizes production API calls during iteration.
Prerequisites
Completed navan-install-auth with working OAuth 2.0 credentials
Node.js 18+ with tsx for TypeScript execution
.env file with NAVAN_CLIENT_ID, NAVAN_CLIENT_SECRET, NAVAN_BASE_URL
Instructions
Step 1: Project Structure
Set up a clean project layout that separates concerns:
my-navan-integration/
โโโ .env # Credentials (NEVER commit)
โโโ .env.example # Template for teammates
โโโ .gitignore # Must include .env, .token-cache, logs/
โโโ src/
โ โโโ navan-client.ts # API wrapper (from navan-sdk-patterns)
โ โโโ navan-types.ts # Response interfaces
โ โโโ index.ts # Entry point
โโโ tests/
โ โโโ fixtures/ # Recorded API responses for offline dev
โ โ โโโ bookings.json
โ โ โโโ users.json
โ โโโ navan-client.test.ts
โโโ logs/ # Request/response logs (gitignored)
โโโ .token-cache # Cached OAuth token (gitignored)
โโโ package.json
โโโ tsconfig.json
Step 2: Environment Configuration
Create .env.example as a safe template and enforce .gitignore:
# .env.example โ commit this file, NOT .env
NAVAN_CLIENT_ID="your-client-id"
NAVAN_CLIENT_SECRET="your-client-secret"
NAVAN_BASE_URL="https://api.navan.com"
NAVAN_LOG_REQUESTS="true"
NAVAN_USE_FIXTURES="false"
A project scaffold with proper secret isolation (.env, .gitignore)
Token caching that avoids redundant auth calls to production
Request/response logging for debugging with secret redaction
Mock fixtures for offline development without production API calls
Dev scripts for live, offline, and recording modes
Error Handling
Error
Code
Cause
Solution
Unauthorized
401
Cached token expired
Delete .token-cache and re-authenticate
Forbidden
403
Credentials lack required scope
Regenerate credentials with proper permissions
Not found
404
Fixture file missing for endpoint
Record fixtures with npm run record
Rate limited
429
Too many dev iterations hitting production
Switch to npm run dev:offline
Server error
500
Navan service issue
Use fixtures; retry later
Maintenance
503
Navan downtime
Use NAVAN_USE_FIXTURES=true for offline mode
Examples
Typical dev workflow:
# 1. First time: record fixtures from production
npm run record
# 2. Daily development: use offline mode
npm run dev:offline
# 3. Integration testing: hit production
npm run test:live
# 4. Debug a failure: check logs
npm run logs
With your local dev environment running, see navan-sdk-patterns for production-grade wrapper patterns, or navan-common-errors when you encounter API failures during development.
