Navan Debug Bundle Skill

Navan Debug Bundle

Overview

Collect diagnostic data from Navan REST API integrations into a structured, shareable debug bundle. Navan has no SDK — all debugging uses raw HTTP requests against their OAuth 2.0 REST endpoints.

Prerequisites

Navan API credentials: client_id and client_secret from Admin > Travel admin > Settings > Integrations
curl and jq installed locally
Credentials are viewable only once at creation — store them in a secret manager immediately
No sandbox environment exists; all API calls hit production

Instructions

Step 1 — Create Bundle Directory

BUNDLE_DIR="navan-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"/{auth,api,connectivity,env}
echo "Bundle initialized: $BUNDLE_DIR"

Step 2 — Capture Environment State

cat > "$BUNDLE_DIR/env/config.txt" <<ENVEOF
Timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
NAVAN_CLIENT_ID: ${NAVAN_CLIENT_ID:+SET (not empty)}${NAVAN_CLIENT_ID:-UNSET}
NAVAN_CLIENT_SECRET: ${NAVAN_CLIENT_SECRET:+SET (not empty)}${NAVAN_CLIENT_SECRET:-UNSET}
NAVAN_TOKEN_URL: ${NAVAN_TOKEN_URL:-https://api.navan.com/ta-auth/oauth/token}
curl version: $(curl --version | head -1)
jq version: $(jq --version 2>/dev/null || echo "not installed")
ENVEOF

Step 3 — Test OAuth Token Acquisition

curl -s -w "\n---HTTP_CODE:%{http_code}---\n" \
  -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" \
  | tee "$BUNDLE_DIR/auth/token-response.json" \
  | jq '{has_token: (.access_token != null), error: .error}'

If the token response returns HTTP 401, the credentials are invalid or expired. If HTTP 403, the API integration may not be enabled for your organization.

Step 4 — Probe API Endpoints

Test each core endpoint and capture full response headers:

TOKEN=$(jq -r '.access_token' "$BUNDLE_DIR/auth/token-response.json")

# Test the primary bookings endpoint
ENDPOINT="v1/bookings"
curl -s -D "$BUNDLE_DIR/api/bookings-headers.txt" \
  -w "\n---HTTP_CODE:%{http_code}---\n" \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.navan.com/${ENDPOINT}?page=0&size=1" \
  > "$BUNDLE_DIR/api/bookings-body.json" 2>&1
echo "bookings: $(grep 'HTTP_CODE' "$BUNDLE_DIR/api/bookings-body.json")"

Step 5 — Connectivity and DNS Tests

curl -s -o /dev/null -w "connect_time: %{time_connect}\nttfb: %{time_starttransfer}\ntotal: %{time_total}\nhttp_code: %{http_code}\n" \
  "https://api.navan.com/ta-auth/oauth/token" \
  > "$BUNDLE_DIR/connectivity/timing.txt"

nslookup api.navan.com > "$BUNDLE_DIR/connectivity/dns.txt" 2>&1

Step 6 — Sanitize and Package

Strip any raw credentials before sharing:

# Remove raw secrets from bundle files
find "$BUNDLE_DIR" -type f -exec sed -i \
  -e "s/$NAVAN_CLIENT_SECRET/[REDACTED]/g" \
  -e "s/$NAVAN_CLIENT_ID/[CLIENT_ID_REDACTED]/g" {} +

tar -czf "${BUNDLE_DIR}.tar.gz" "$BUNDLE_DIR"
echo "Debug bundle ready: ${BUNDLE_DIR}.tar.gz ($(du -h "${BUNDLE_DIR}.tar.gz" | cut -f1))"

Output

A compressed tarball containing:

| File | Contents | |------|----------| | auth/token-response.json | OAuth response (token redacted) | | api/*-headers.txt | HTTP response headers per endpoint | | api/*-body.json | API response bodies | | connectivity/timing.txt | Connection timing metrics | | connectivity/dns.txt | DNS resolution results | | env/config.txt | Environment variable state |

Error Handling

| HTTP Code | Meaning | Action | |-----------|---------|--------| | 401 | Invalid or expired credentials | Regenerate credentials in Admin > Integrations | | 403 | API not enabled for organization | Contact Navan admin to enable API access | | 429 | Rate limit exceeded | Wait and retry; check Retry-After header | | 500 | Navan server error | Retry after 60s; check Navan status | | ECONNREFUSED | Cannot reach Navan | Check DNS, firewall, and proxy settings |

Examples

Parse a specific error from the bundle:

# Extract error details from a failed endpoint
jq '.error, .message, .status' "$BUNDLE_DIR/api/bookings-body.json"

# Check if token is expired
jq '.expires_at' "$BUNDLE_DIR/auth/token-response.json"

# Review response times
cat "$BUNDLE_DIR/connectivity/timing.txt"

Resources

Navan Help Center — Support documentation and troubleshooting
Navan Security — SOC 2 Type II, ISO 27001 compliance details
Navan Integrations — Available third-party connectors

Next Steps

Use navan-incident-runbook if the debug bundle reveals a production incident
Use navan-rate-limits if 429 errors appear in the bundle
Use navan-common-errors for guidance on specific HTTP error codes

Agent Skills: Navan Debug Bundle

Install this agent skill to your local

Skill Files