Navan User Management API Guide

Auth method: OAuth 2.0 (client credentials)

Setup steps

1. Log in to the Navan Admin portal and navigate to Settings > Integrations > API.
2. Create an API application to obtain a client_id and client_secret.
3. POST to the token endpoint (https://api.navan.com/auth/v1/token) with grant_type=client_credentials, client_id, and client_secret.
4. Use the returned Bearer access token in the Authorization header for all subsequent API requests.

Required scopes

List Users

• Method: GET
• URL: https://api.navan.com/travel/v1/users
• Watch out for: Cursor-based pagination; do not use offset. nextCursor is null on the last page.

Request example

GET /travel/v1/users?cursor=abc123&limit=50
Authorization: Bearer {token}

Response example

{
  "data": [{"id":"usr_1","email":"jane@co.com","firstName":"Jane"}],
  "nextCursor": "def456"
}

Get User

• Method: GET
• URL: https://api.navan.com/travel/v1/users/{userId}
• Watch out for: Returns 404 for deactivated users in some configurations; check active flag.

Request example

GET /travel/v1/users/usr_1
Authorization: Bearer {token}

Response example

{
  "id": "usr_1",
  "email": "jane@co.com",
  "firstName": "Jane",
  "active": true
}

Create User

• Method: POST
• URL: https://api.navan.com/travel/v1/users
• Watch out for: Duplicate email returns 409 Conflict; check for existing deactivated accounts with the same email before creating.

Request example

POST /travel/v1/users
Content-Type: application/json

{"email":"bob@co.com","firstName":"Bob","lastName":"Smith"}

Response example

{
  "id": "usr_2",
  "email": "bob@co.com",
  "active": true,
  "createdAt": "2025-01-10T12:00:00Z"
}

Update User

• Method: PATCH
• URL: https://api.navan.com/travel/v1/users/{userId}
• Watch out for: PATCH is partial update; omitted fields are not cleared. Use explicit null to clear a field if supported.

Request example

PATCH /travel/v1/users/usr_2
Content-Type: application/json

{"department":"Engineering","costCenter":"CC-101"}

Response example

{
  "id": "usr_2",
  "department": "Engineering",
  "costCenter": "CC-101"
}

Deactivate User

• Method: DELETE
• URL: https://api.navan.com/travel/v1/users/{userId}
• Watch out for: This performs a soft deactivation, not a hard delete. The user record is retained for audit/expense history.

Request example

DELETE /travel/v1/users/usr_2
Authorization: Bearer {token}

Response example

HTTP 204 No Content

SCIM List Users

• Method: GET
• URL: https://api.navan.com/scim/v2/Users
• Watch out for: SCIM token is separate from the REST API OAuth token; generated in Admin > SCIM settings.

Request example

GET /scim/v2/Users?filter=userName+eq+"jane@co.com"
Authorization: Bearer {scim_token}

Response example

{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults":1,
  "Resources":[{"id":"usr_1","userName":"jane@co.com"}]
}

SCIM Create User

• Method: POST
• URL: https://api.navan.com/scim/v2/Users
• Watch out for: Enterprise plan required. SCIM provisioning must be enabled by a Navan admin before the endpoint is active.

Request example

POST /scim/v2/Users
Content-Type: application/scim+json

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bob@co.com","name":{"givenName":"Bob","familyName":"Smith"}}

Response example

{
  "id": "usr_2",
  "userName": "bob@co.com",
  "active": true
}

SCIM Update User (Replace)

• Method: PUT
• URL: https://api.navan.com/scim/v2/Users/{userId}
• Watch out for: PUT replaces the full resource; omitted attributes may be cleared. Prefer PATCH for partial updates if supported by your IdP connector.

Request example

PUT /scim/v2/Users/usr_2
Content-Type: application/scim+json

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName":"bob@co.com","active":false}

Response example

{
  "id": "usr_2",
  "active": false
}

• Rate limits: Navan's public developer docs do not explicitly publish rate-limit tiers or numeric thresholds as of the policy date.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: Contact Navan support or review your API application dashboard for current rate-limit details.

• Pagination method: cursor

• Default page size: Not documented

• Max page size: Not documented

• Pagination pointer: cursor

• Webhooks available: No

• Webhook notes: Navan's public developer documentation does not describe outbound webhook support for user-management events as of the policy date.

• Alternative event strategy: Poll the List Users endpoint with updatedAt filtering, or use SCIM provisioning events from your IdP.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: https://api.navan.com/scim/v2

• Supported operations: GET /Users (list and filter), GET /Users/{id}, POST /Users (create), PUT /Users/{id} (replace), PATCH /Users/{id} (partial update), DELETE /Users/{id} (deactivate)

Limitations:

• Requires Enterprise plan.
• SCIM must be explicitly enabled by a Navan admin in the Admin portal.
• SCIM bearer token is distinct from the REST API OAuth token.
• Group/role provisioning support via SCIM is not fully documented publicly; verify with Navan support.
• IdP-specific connector URLs may differ from the base SCIM endpoint; confirm in Admin > SCIM settings.

Three integration patterns cover the majority of lifecycle automation needs.

Onboarding via REST: POST to /travel/v1/users with email, firstName, lastName, department, costCenter, and travelPolicy.

Capture the returned id immediately for identity graph registration.

If the POST returns 409, a deactivated record with that email already exists - PATCH the existing record with active: true rather than creating a duplicate.

Deprovisioning via SCIM: Configure the SCIM bearer token in your IdP connector.

On employee departure, the IdP sends PATCH /scim/v2/Users/{id} with active: false or a DELETE;

Navan soft-deactivates the record and preserves expense history.

Confirm with GET /scim/v2/Users/{id} and assert active: false.

Hard deletion is not supported via SCIM.

Bulk attribute sync via REST: Paginate GET /travel/v1/users with cursor to retrieve all active users, then PATCH individual records for department and costCenter changes.

Log updatedAt on each response - concurrent SCIM and REST writes to the same user can produce race conditions, so coordinate update sources or delegate attribute ownership exclusively to SCIM.

Onboard a new employee via REST API

1. Obtain OAuth 2.0 Bearer token via POST /auth/v1/token with client credentials.
2. POST /travel/v1/users with email, firstName, lastName, department, costCenter, and travelPolicy.
3. Capture the returned user id for downstream system mapping.
4. Optionally PATCH /travel/v1/users/{id} to assign manager and expensePolicy after HR data is available.

Watch out for: If the employee's email already exists as a deactivated account, the POST returns 409. PATCH the existing record with active:true instead.

Deprovision a departing employee via SCIM

1. Ensure SCIM is enabled in Navan Admin portal and the SCIM bearer token is configured in your IdP.
2. Trigger deprovisioning in your IdP (Okta, Entra ID, etc.); the IdP sends PATCH /scim/v2/Users/{id} with active:false or DELETE /scim/v2/Users/{id}.
3. Navan soft-deactivates the user, revoking travel booking access while retaining expense history.
4. Verify deactivation by GET /scim/v2/Users/{id} and confirming active:false.

Watch out for: SCIM deactivation is a soft delete; the user record persists. Hard deletion is not supported via SCIM.

Bulk-sync department and cost center updates

1. Obtain OAuth 2.0 Bearer token.
2. GET /travel/v1/users with cursor pagination to retrieve all active users.
3. For each user requiring update, PATCH /travel/v1/users/{id} with updated department and costCenter fields.
4. Log updatedAt timestamps to detect conflicts with concurrent IdP-driven SCIM updates.

Watch out for: Concurrent REST API and SCIM updates to the same user may cause race conditions; coordinate update sources or use SCIM exclusively for attribute sync.

The most common integration trap is treating the REST API and SCIM surface as interchangeable. They use separate auth tokens, separate endpoint trees, and have partially overlapping but not identical field semantics - a PATCH via REST and a PATCH via SCIM may behave differently for the same attribute.

A second trap is the PUT behavior on SCIM: PUT /scim/v2/Users/{id} replaces the full resource, meaning omitted attributes can be silently cleared; prefer PATCH for partial updates wherever your IdP connector supports it.

Finally, SCIM group and role provisioning support is not fully documented publicly - do not assume role assignment via SCIM works without validating against a test user in your environment and confirming behavior with Navan support before rolling out to production.