Navan Multi Env Setup

---
name: navan-multi-env-setup
description: "'Set up dev/staging/prod environment separation for Navan integrations without a sandbox API. Use when configuring multiple environments, building CI test pipelines, or setting up local development. Trigger with \"navan environments\", \"navan multi env\", \"navan dev setup\", \"navan mock server\". '"
allowed-tools: "Read, Write, Edit, Bash(npm:*), Grep"
category: backend-and-data
source_repo: jeremylongshore/claude-code-plugins-plus-skills
source_path: "skills/.curated/navan-multi-env-setup/SKILL.md"
source_url: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/HEAD/skills/.curated/navan-multi-env-setup/SKILL.md
---

# Navan Multi-Environment Setup

## Overview

Navan does not offer a sandbox or staging API — every call hits production data with real corporate bookings and expense records. This creates risk for development and testing: a bug in a sync script could modify live itineraries, and CI pipelines cannot safely run integration tests. This skill implements environment isolation using separate OAuth apps, environment variable validation, a local development proxy, and a CI mock server.

## Prerequisites

- Navan admin access to create multiple OAuth apps (Admin > Travel admin > Settings > Integrations)
- Node.js 18+ for proxy and mock server
- Understanding of OAuth 2.0 client credentials flow (see `navan-install-auth`)
- `.env` management tooling (dotenv, direnv, or cloud secret manager)

## Instructions

### Step 1: Create Per-Environment OAuth Apps

Create separate API credentials in the Navan admin dashboard for each environment. This provides natural isolation — the dev app can have read-only scopes while production gets full access.

```bash
# .env.development — read-only scoped OAuth app
NAVAN_ENV=development
NAVAN_CLIENT_ID=dev-client-id-xxxxx
NAVAN_CLIENT_SECRET=dev-client-secret-xxxxx
NAVAN_API_BASE=https://api.navan.com/v1
NAVAN_READ_ONLY=true

# .env.staging — read + limited write, separate audit trail
NAVAN_ENV=staging
NAVAN_CLIENT_ID=stg-client-id-xxxxx
NAVAN_CLIENT_SECRET=stg-client-secret-xxxxx
NAVAN_API_BASE=https://api.navan.com/v1
NAVAN_READ_ONLY=false

# .env.production — full access, rotation-managed
NAVAN_ENV=production
NAVAN_CLIENT_ID=prod-client-id-xxxxx
NAVAN_CLIENT_SECRET=prod-client-secret-xxxxx
NAVAN_API_BASE=https://api.navan.com/v1
NAVAN_READ_ONLY=false
```

### Step 2: Build an Environment-Aware Client

```typescript
import { config } from 'dotenv';

interface NavanConfig {
  env: string;
  clientId: string;
  clientSecret: string;
  apiBase: string;
  readOnly: boolean;
}

function loadConfig(): NavanConfig {
  const envFile = `.env.${process.env.NODE_ENV || 'development'}`;
  config({ path: envFile });

  const required = ['NAVAN_CLIENT_ID', 'NAVAN_CLIENT_SECRET', 'NAVAN_API_BASE'];
  for (const key of required) {
    if (!process.env[key]) {
      throw new Error(`Missing ${key} in ${envFile}`);
    }
  }

  return {
    env: process.env.NAVAN_ENV || 'development',
    clientId: process.env.NAVAN_CLIENT_ID!,
    clientSecret: process.env.NAVAN_CLIENT_SECRET!,
    apiBase: process.env.NAVAN_API_BASE!,
    readOnly: process.env.NAVAN_READ_ONLY === 'true'
  };
}

class NavanClient {
  private config: NavanConfig;
  private accessToken: string | null = null;

  constructor() {
    this.config = loadConfig();
    console.log(`Navan client initialized [${this.config.env}] readOnly=${this.config.readOnly}`);
  }

  async request(method: string, path: string, body?: object): Promise<any> {
    // Block writes in read-only environments
    if (this.config.readOnly && method !== 'GET') {
      throw new Error(`Write operations blocked in ${this.config.env} (read-only mode)`);
    }

    if (!this.accessToken) {
      this.accessToken = await this.authenticate();
    }

    const response = await fetch(`${this.config.apiBase}${path}`, {
      method,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Content-Type': 'application/json'
      },
      body: body ? JSON.stringify(body) : undefined
    });

    if (!response.ok) {
      throw new Error(`Navan API error: HTTP ${response.status} on ${method} ${path}`);
    }
    return response.json();
  }

  private async authenticate(): Promise<string> {
    const res = await fetch('https://api.navan.com/ta-auth/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.config.clientId,
        client_secret: this.config.clientSecret
      })
    });
    const { access_token } = await res.json();
    return access_token;
  }
}
```

### Step 3: Create a Local Development Proxy

```typescript
import express from 'express';

// Proxy that logs all requests and optionally blocks writes
const proxy = express();

proxy.use(express.json());
proxy.all('/navan/*', async (req, res) => {
  const navanPath = req.path.replace('/navan', '');
  const method = req.method;

  // Log every request for debugging
  console.log(`[PROXY] ${method} ${navanPath}`);
  if (req.body && Object.keys(req.body).length > 0) {
    console.log(`[PROXY] Body:`, JSON.stringify(req.body, null, 2));
  }

  // In dev mode, block mutating operations
  if (process.env.NAVAN_READ_ONLY === 'true' && method !== 'GET') {
    console.log(`[PROXY] BLOCKED: ${method} ${navanPath} (read-only mode)`);
    return res.status(403).json({
      error: 'Write operation blocked in development mode',
      method, path: navanPath
    });
  }

  // Forward to real Navan API
  try {
    const response = await fetch(`https://api.navan.com/v1${navanPath}`, {
      method,
      headers: {
        'Authorization': req.headers.authorization as string,
        'Content-Type': 'application/json'
      },
      body: ['POST', 'PUT', 'PATCH'].includes(method)
        ? JSON.stringify(req.body) : undefined
    });

    const data = await response.json();
    console.log(`[PROXY] Response: ${response.status}`);
    res.status(response.status).json(data);
  } catch (err: any) {
    console.error(`[PROXY] Error:`, err.message);
    res.status(502).json({ error: 'Proxy error', message: err.message });
  }
});

proxy.listen(4000, () => console.log('Navan dev proxy on http://localhost:4000'));
```

### Step 4: Build a CI Mock Server

```typescript
import express from 'express';
const mock = express();
mock.use(express.json());

// Mock data store
const mockData = {
  users: [
    { id: 'user-001', email: 'traveler@company.com', role: 'traveler', department: 'engineering' }
  ],
  trips: [
    { id: 'trip-001', traveler_id: 'user-001', status: 'confirmed', total: 450.00 }
  ],
  expenses: [
    { id: 'exp-001', submitter_id: 'user-001', amount: 125.50, status: 'submitted' }
  ]
};

// OAuth token endpoint
mock.post('/ta-auth/oauth/token', (req, res) => {
  res.json({ access_token: 'mock-token-ci', expires_in: 3600, token_type: 'Bearer' });
});

// Users
mock.get('/v1/users', (req, res) => {
  res.json({ data: mockData.users, total: mockData.users.length, has_more: false });
});

// Trips
mock.get('/v1/trips', (req, res) => {
  res.json({ data: mockData.trips, total: mockData.trips.length, has_more: false });
});

// Expenses
mock.get('/v1/expenses', (req, res) => {
  res.json({ data: mockData.expenses, total: mockData.expenses.length, has_more: false });
});

// Catch-all for unimplemented endpoints
mock.all('*', (req, res) => {
  console.log(`[MOCK] Unhandled: ${req.method} ${req.path}`);
  res.status(501).json({ error: 'Not implemented in mock', path: req.path });
});

const port = process.env.MOCK_PORT || 4001;
mock.listen(port, () => console.log(`Navan mock server on http://localhost:${port}`));
```

### Step 5: Wire Mock Server into CI

```yaml
# .github/workflows/test.yml
- name: Start Navan mock server
  run: |
    node navan-mock-server.js &
    sleep 2
  env:
    MOCK_PORT: 4001

- name: Run integration tests
  run: npm test
  env:
    NAVAN_API_BASE: http://localhost:4001/v1
    NAVAN_CLIENT_ID: ci-test-client
    NAVAN_CLIENT_SECRET: ci-test-secret
    NODE_ENV: test
```

## Output

A complete environment isolation strategy for Navan integrations: separate OAuth apps per environment with scoped permissions, an environment-aware client with write protection, a local dev proxy for request logging and mutation blocking, and a CI-ready mock server that eliminates production API dependencies from automated tests.

## Error Handling

| Error | Code | Solution |
|-------|------|----------|
| Missing env vars | N/A | Config loader throws on startup; check the correct `.env.<environment>` file exists |
| Write blocked in read-only | 403 | Expected in dev mode; switch to staging/prod for write operations |
| Mock endpoint not found | 501 | Add the endpoint to mock server; check test expectations match mock data |
| Proxy connection refused | 502 | Ensure the proxy server is running; check port availability |
| Wrong environment loaded | N/A | Verify NODE_ENV matches the intended `.env.<environment>` file |

## Examples

**Validate environment configuration:**

```bash
# Check which environment would load
NODE_ENV=staging node -e "
  require('dotenv').config({ path: '.env.staging' });
  console.log('ENV:', process.env.NAVAN_ENV);
  console.log('READ_ONLY:', process.env.NAVAN_READ_ONLY);
  console.log('CLIENT_ID:', process.env.NAVAN_CLIENT_ID?.slice(0, 8) + '...');
"
```

**Run tests against mock server locally:**

```bash
# Terminal 1: Start mock
MOCK_PORT=4001 node navan-mock-server.js

# Terminal 2: Run tests
NAVAN_API_BASE=http://localhost:4001/v1 npm test
```

## Resources

- [Navan Help Center](https://app.navan.com/app/helpcenter) — API credential creation and management
- [Navan Integrations](https://navan.com/integrations) — Available integration patterns and partners
- [Navan Security](https://navan.com/security) — Data handling and environment security policies
- [dotenv Documentation](https://github.com/motdotla/dotenv) — Environment variable management for Node.js

## Next Steps

After setting up environments, see `navan-security-basics` for credential rotation across all environments, or `navan-ci-integration` for building the full CI/CD pipeline with Navan API tests.

---

**Source:** [`jeremylongshore/claude-code-plugins-plus-skills`](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) → `skills/.curated/navan-multi-env-setup/SKILL.md`

**Also appears in:** `jeremylongshore/claude-code-plugins-plus-skills/plugins/saas-packs/navan-pack/skills/navan-multi-env-setup/SKILL.md`