Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/navan-pack/skills/navan-incident-runbook/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill navan-incident-runbook. Copyright stays with the author (MIT).

Navan Incident Runbook

Overview

Structured incident response for Navan travel platform disruptions. Navan uses raw REST APIs with OAuth 2.0 — there is no SDK and no sandbox. All diagnostic commands run against production.

Prerequisites

• Access to Navan admin console (Admin > Travel admin)
• OAuth credentials (client_id, client_secret) stored in your secret manager
• Familiarity with Navan's Ava AI assistant (in-app chat, first-line support)
• curl and jq for API health probing

Instructions

Step 1 — Classify Severity

Step 2 — Triage with Ava AI

Before manual debugging, use Navan's built-in AI assistant:

1. Open the Navan app or visit app.navan.com
2. Click the Ava chat icon (bottom-right)
3. Describe the issue — Ava can check booking status, rebook flights, and surface known outages
4. If Ava cannot resolve, proceed to API health checks

Step 3 — API Health Check

# Test OAuth authentication
AUTH_RESPONSE=$(curl -s -w "\n%{http_code}" \
  -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")

HTTP_CODE=$(echo "$AUTH_RESPONSE" | tail -1)
BODY=$(echo "$AUTH_RESPONSE" | sed '$d')

echo "Auth endpoint: HTTP $HTTP_CODE"
echo "$BODY" | jq '{token_present: (.access_token != null), error: .error}' 2>/dev/null

# Test booking retrieval (requires valid token)
TOKEN=$(echo "$BODY" | jq -r '.access_token')
curl -s -w "\nHTTP %{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.navan.com/v1/bookings?page=0&size=50" | tail -1

Step 4 — Incident-Specific Playbooks

Booking API Failure (P1/P2):

1. Confirm via API health check above — look for HTTP 500/503
2. Check if the issue is flight-specific or hotel-specific by testing both trip types
3. Direct travelers to Navan mobile app or phone support as fallback
4. Queue failed booking requests for retry with exponential backoff

OAuth Token Failure (P1):

1. Test with curl against /ta-auth/oauth/token — expect HTTP 200 with access_token field
2. If HTTP 401: credentials may be rotated; check Admin > Integrations
3. If HTTP 403: API access may be revoked; contact Navan admin
4. Re-request a token via POST /ta-auth/oauth/token with grant_type=client_credentials

Expense Sync Failure (P2/P3):

1. Check the Expense Transaction API status — this endpoint requires separate enablement
2. Verify your Fivetran/Airbyte connector status if using a data pipeline
3. Check TRANSACTION table freshness — incremental sync may be lagging
4. Validate that expense categories map correctly to your ERP

Flight Cancellation / Disruption (P2):

1. Use Ava AI to check rebooking options — Ava handles most rebookings automatically
2. Verify traveler's profile has correct loyalty program numbers
3. Check /v1/bookings for the affected booking UUID
4. Coordinate with travel admin for policy exception approvals if rebooking exceeds budget

Step 5 — Escalation Path

Step 6 — Post-Incident Review

After resolution, create a post-incident record:

cat > "incident-$(date +%Y%m%d-%H%M%S).md" <<'INCEOF'
## Incident Report
- **Severity**: P?
- **Duration**: Start — End
- **Impact**: Number of affected travelers/bookings
- **Root Cause**: (API outage / credential issue / sync failure / ...)
- **Resolution**: Steps taken
- **Prevention**: Changes to avoid recurrence
INCEOF

Output

• Severity classification for the incident
• API health check results confirming platform vs local issue
• Executed playbook steps with outcomes
• Escalation actions taken with timestamps
• Post-incident report document

Error Handling

Examples

Quick API status check during an incident:

# One-liner health probe
curl -s -o /dev/null -w "Auth: %{http_code} (%{time_total}s)\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"

Resources

• Navan Help Center — Support portal and known issues
• Navan Security — Infrastructure and compliance details
• Navan Integrations — Connector status and documentation

Next Steps

• Use navan-debug-bundle to collect full diagnostic data for support tickets
• Use navan-prod-checklist to harden your integration against future incidents
• Use navan-common-errors for detailed error code interpretation