navan-deploy-integration

What this skill does

# 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:

```bash
# 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:**

| 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 |

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:**

```bash
# 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

| 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:**

```bash
#!/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](https://app.navan.com/app/helpcenter) — Integration setup guides
- [Navan Integrations Directory](https://navan.com/integrations) — Full list of supported connectors
- [SCIM Protocol Spec (RFC 7644)](https://datatracker.ietf.org/doc/html/rfc7644) — SCIM provisioning standard
- [Navan Pricing](https://navan.com/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