Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/navan-deploy-integration/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill navan-deploy-integration. Copyright stays with the author (MIT).

Navan Deploy Integration

Overview

Navan connects to enterprise systems through multiple integration methods: direct REST API with OAuth 2.0, SCIM for user provisioning, SFTP for batch file exchange, SAML/OIDC for SSO, and webhooks for real-time events. There is no SDK — all integrations use Navan's REST endpoints or admin console configuration. This skill provides deployment checklists for the three most common integration categories: ERP expense sync, HRIS user provisioning, and identity provider SSO.

Prerequisites

• Navan Admin account with integration management permissions
• OAuth 2.0 credentials — client_id and client_secret from Admin > API Settings
• Target system admin access — NetSuite/Sage Intacct/Xero admin, Workday/BambooHR admin, or Okta/Azure AD admin
• API base URL: https://api.navan.com/v1

Instructions

Category A — ERP Expense Sync (NetSuite, Sage Intacct, Xero, QuickBooks)

Deployment Checklist:

1. Create OAuth credentials in Navan Admin > API Settings
2. Configure GL code mappings — Map Navan expense categories to your chart of accounts
3. Set cost center mappings — Align Navan departments with ERP cost centers
4. Enable expense export via REST API:

# Fetch approved expenses ready for ERP sync
curl -s -X GET "https://api.navan.com/v1/expenses?status=approved&limit=50" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

# Response includes fields for ERP mapping:
# {
#   "uuid": "exp_abc123",
#   "amount": 245.50,
#   "currency": "USD",
#   "category": "meals_entertainment",
#   "cost_center": "engineering",
#   "gl_code": "6200",
#   "receipt_url": "https://api.navan.com/v1/receipts/exp_abc123",
#   "approved_at": "2026-03-20T14:30:00Z"
# }

1. Set up sync schedule — Navan supports daily or real-time export via webhooks
2. Validate with test expenses — Submit 3-5 test expenses through the full approval flow
3. Enable in production — Switch from sandbox to production OAuth credentials

Category B — HRIS User Provisioning (Workday, BambooHR, ADP)

SCIM Provisioning Setup:

1. Enable SCIM in Navan Admin > Integrations > User Provisioning
2. Configure SCIM endpoint in your HRIS:
   • SCIM Base URL: https://api.navan.com/scim/v2
   • Authentication: OAuth 2.0 Bearer Token
3. Map user attributes:

1. Test provisioning — Create a test user in HRIS and verify they appear in Navan within 15 minutes
2. Test deprovisioning — Deactivate the test user and confirm Navan access is revoked
3. Verify via API:

# Check provisioned users
curl -s "https://api.navan.com/v1/users?provisioning_source=scim&limit=10" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | jq '.[] | {email, status, provisioned_at}'

Category C — SSO Deployment (Okta, Azure AD)

SAML Configuration:

1. Create SAML application in your IdP (Okta or Azure AD)
2. Configure Navan SAML settings in Admin > Security > SSO:
   • Entity ID: https://app.navan.com/saml/metadata
   • ACS URL: https://app.navan.com/saml/acs
   • Name ID Format: emailAddress
3. Map SAML attributes:

email       → user.email        (Required)
firstName   → user.firstName    (Required)
lastName    → user.lastName     (Required)
department  → user.department   (Optional — enables policy routing)

1. Upload IdP metadata XML to Navan Admin console
2. Enable JIT provisioning (optional) — Auto-create Navan accounts on first SSO login
3. Test with a pilot group — Assign 5-10 users before org-wide rollout
4. Enforce SSO — After pilot validation, enable "SSO Required" to disable password login

Output

Each integration deployment produces:

• Connection validation confirming data flows between systems
• Field mapping documentation for ongoing maintenance
• Test results from pilot user group
• Rollback instructions if issues arise post-deployment

Error Handling

Examples

Automated daily expense export to NetSuite:

#!/usr/bin/env bash
# scripts/navan-netsuite-sync.sh
set -euo pipefail

# Authenticate
TOKEN=$(curl -sf -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')

# Fetch yesterday's approved expenses
YESTERDAY=$(date -d "yesterday" +%Y-%m-%d)
curl -s "https://api.navan.com/v1/expenses?status=approved&approved_after=${YESTERDAY}T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN" \
  -o /tmp/navan-expenses.json

EXPENSE_COUNT=$(jq length /tmp/navan-expenses.json)
echo "Exporting $EXPENSE_COUNT expenses to NetSuite"

Resources

• Navan Help Center — Integration setup guides
• Navan Integrations Directory — Full list of supported connectors
• SCIM Protocol Spec (RFC 7644) — SCIM provisioning standard
• Navan Pricing — Plan comparison for integration availability

Next Steps

• Add navan-observability to monitor integration health post-deployment
• Add navan-webhooks-events for real-time event-driven sync instead of polling
• See navan-security-basics for credential rotation and access control