Navan Deploy Integration Skill

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:

Create OAuth credentials in Navan Admin > API Settings
Configure GL code mappings — Map Navan expense categories to your chart of accounts
Set cost center mappings — Align Navan departments with ERP cost centers
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"
# }

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

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

SCIM Provisioning Setup:

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

| HRIS Field | Navan SCIM Attribute | Required | |------------|---------------------|----------| | Email | userName | Yes | | First Name | name.givenName | Yes | | Last Name | name.familyName | Yes | | Department | urn:navan:department | Recommended | | Manager | urn:navan:manager_email | Recommended | | Cost Center | urn:navan:cost_center | Optional |

Test provisioning — Create a test user in HRIS and verify they appear in Navan within 15 minutes
Test deprovisioning — Deactivate the test user and confirm Navan access is revoked
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:

Create SAML application in your IdP (Okta or Azure AD)
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
Map SAML attributes:

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

Upload IdP metadata XML to Navan Admin console
Enable JIT provisioning (optional) — Auto-create Navan accounts on first SSO login
Test with a pilot group — Assign 5-10 users before org-wide rollout
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

| HTTP Code | Meaning | Resolution | |-----------|---------|------------| | 400 | Invalid field mapping or malformed request | Review GL code / attribute mappings | | 401 | OAuth token expired or invalid | Rotate credentials in Navan Admin | | 403 | Integration not enabled for your plan | Verify Navan plan includes this integration (Enterprise required for some) | | 409 | Duplicate user in SCIM provisioning | Check for existing user with same email | | 422 | Validation error on expense export | Verify required fields (amount, currency, category) are present | | 429 | Rate limited | Reduce sync frequency or implement exponential backoff |

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

Agent Skills: Navan Deploy Integration

Install this agent skill to your local

Skill Files