Vanta User Management API Guide

Auth method: OAuth 2.0 (client credentials flow); API tokens also supported for direct access

Setup steps

1. Navigate to Settings > API Tokens in the Vanta dashboard.
2. Create a new API token, selecting the required scopes.
3. For OAuth 2.0 client credentials: register an OAuth application in the Vanta developer settings to obtain client_id and client_secret.
4. Exchange client credentials for a bearer token via POST https://api.vanta.com/oauth/token with grant_type=client_credentials.
5. Include the bearer token in the Authorization header: 'Authorization: Bearer '.

Required scopes

List People

• Method: GET
• URL: https://api.vanta.com/v1/people
• Watch out for: Pagination is cursor-based; iterate using pageInfo.nextPageCursor until hasNextPage is false.

Request example

GET /v1/people?pageSize=100 HTTP/1.1
Host: api.vanta.com
Authorization: Bearer <token>

Response example

{
  "data": [
    {"id": "ppl_abc123", "displayName": "Jane Doe", "email": "jane@example.com"}
  ],
  "pageInfo": {"nextPageCursor": "cursor_xyz", "hasNextPage": true}
}

Get Person by ID

• Method: GET
• URL: https://api.vanta.com/v1/people/{personId}
• Watch out for: Returns 404 if the person ID does not exist or the token lacks read scope.

Request example

GET /v1/people/ppl_abc123 HTTP/1.1
Host: api.vanta.com
Authorization: Bearer <token>

Response example

{
  "data": {
    "id": "ppl_abc123",
    "displayName": "Jane Doe",
    "email": "jane@example.com",
    "employmentStatus": "EMPLOYED"
  }
}

Create Person

• Method: POST
• URL: https://api.vanta.com/v1/people
• Watch out for: Email must be unique; duplicate email returns a 409 conflict error.

Request example

POST /v1/people HTTP/1.1
Host: api.vanta.com
Authorization: Bearer <token>
Content-Type: application/json

{"displayName": "John Smith", "email": "john@example.com", "employmentStatus": "EMPLOYED"}

Response example

{
  "data": {
    "id": "ppl_def456",
    "displayName": "John Smith",
    "email": "john@example.com"
  }
}

Update Person

• Method: PATCH
• URL: https://api.vanta.com/v1/people/{personId}
• Watch out for: Only fields included in the request body are updated; omitted fields retain existing values.

Request example

PATCH /v1/people/ppl_def456 HTTP/1.1
Host: api.vanta.com
Authorization: Bearer <token>
Content-Type: application/json

{"title": "Senior Engineer", "department": "Engineering"}

Response example

{
  "data": {
    "id": "ppl_def456",
    "title": "Senior Engineer",
    "department": "Engineering"
  }
}

Offboard / Deactivate Person

• Method: PATCH
• URL: https://api.vanta.com/v1/people/{personId}
• Watch out for: Setting employmentStatus to TERMINATED triggers offboarding workflows in Vanta; verify downstream task assignments before calling.

Request example

PATCH /v1/people/ppl_def456 HTTP/1.1
Host: api.vanta.com
Authorization: Bearer <token>
Content-Type: application/json

{"employmentStatus": "TERMINATED", "endDate": "2025-06-01"}

Response example

{
  "data": {
    "id": "ppl_def456",
    "employmentStatus": "TERMINATED",
    "endDate": "2025-06-01"
  }
}

List Users (Vanta account users with roles)

• Method: GET
• URL: https://api.vanta.com/v1/users
• Watch out for: Vanta distinguishes 'people' (employees tracked for compliance) from 'users' (Vanta platform accounts). Confirm which resource matches your use case.

Request example

GET /v1/users HTTP/1.1
Host: api.vanta.com
Authorization: Bearer <token>

Response example

{
  "data": [
    {"id": "usr_111", "email": "admin@example.com", "role": "ADMIN"}
  ],
  "pageInfo": {"hasNextPage": false}
}

• Rate limits: Vanta's public developer docs do not explicitly publish specific rate limit numbers or tier-based limits as of the last known documentation state.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No explicit rate limit values, headers, or Retry-After behavior documented in official sources. Contact Vanta support for current limits.

• Pagination method: cursor

• Default page size: 100

• Max page size: 100

• Pagination pointer: pageCursor

• Webhooks available: No

• Webhook notes: Vanta's public developer documentation does not describe a native outbound webhook system for user/people events as of the last known documentation state.

• Alternative event strategy: Poll the /v1/people endpoint on a schedule to detect changes, or use SCIM provisioning events via your IdP for user lifecycle events.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Enterprise

• Endpoint: Provided by Vanta during SCIM setup in Settings > SSO & SCIM; tenant-specific URL generated per IdP connection.

• Supported operations: Create user (POST /Users), Update user (PATCH /Users/{id}), Deactivate user (PATCH /Users/{id} with active=false), List users (GET /Users), Get user (GET /Users/{id})

Limitations:

• Requires SSO to be configured as a prerequisite before SCIM can be enabled.
• Enterprise plan required; not available on Core, Plus, or Growth tiers.
• SCIM endpoint URL is IdP-specific and generated within Vanta settings; not a static public URL.
• Supported IdPs include Okta, Microsoft Entra ID (Azure AD), and Google Workspace; OneLogin not listed as officially supported.
• Group provisioning support may vary by IdP; verify in Vanta help docs for your specific IdP.

Three primary automation scenarios are well-supported by the API.

For employee onboarding, POST to /v1/people with displayName, email, employmentStatus=EMPLOYED, startDate, title, and department;

a 409 conflict means the email already exists (likely from an HRIS sync) - use PATCH on the existing record instead.

For offboarding, PATCH /v1/people/{personId} with employmentStatus=TERMINATED and endDate;

this triggers Vanta's internal offboarding task workflows, but does not revoke SSO login - IdP deprovisioning or SCIM must handle that separately.

For Enterprise customers, SCIM 2.0 provisioning via Okta, Microsoft Entra ID, or Google Workspace automates the full lifecycle;

SCIM deprovisioning sets active=false and marks the person as terminated while preserving compliance history.

Webhooks for people/user events are not documented in Vanta's public developer docs;

use scheduled polling of /v1/people as the fallback for change detection.

Onboard a new employee via REST API

1. Obtain a bearer token via OAuth 2.0 client credentials with vanta-api.people:write scope.
2. POST to https://api.vanta.com/v1/people with displayName, email, employmentStatus=EMPLOYED, startDate, title, and department.
3. Store the returned id for future updates or offboarding.
4. Verify the person appears in Vanta's People list and that compliance tasks are auto-assigned.

Watch out for: If the email already exists in Vanta (e.g., imported from an HRIS integration), the POST will return 409. Use PATCH to update the existing record instead.

Offboard a terminated employee

1. Retrieve the person's Vanta ID via GET /v1/people?email=user@example.com or from your internal mapping.
2. PATCH /v1/people/{personId} with employmentStatus=TERMINATED and endDate set to the termination date.
3. Confirm offboarding tasks are triggered in Vanta's task dashboard.
4. If the person also has a Vanta platform login, verify their access is revoked via SSO/SCIM or manually in Settings.

Watch out for: Setting TERMINATED via API does not automatically revoke SSO access; IdP deprovisioning or SCIM must handle login deactivation separately.

Sync employees from HRIS using SCIM (Enterprise)

1. Confirm Enterprise plan and SSO are active in Vanta.
2. Navigate to Settings > SSO & SCIM in Vanta and enable SCIM provisioning for your IdP (Okta, Entra ID, or Google Workspace).
3. Copy the tenant-specific SCIM base URL and bearer token generated by Vanta.
4. Configure the SCIM application in your IdP with the Vanta SCIM URL and token.
5. Map IdP user attributes to SCIM standard attributes (userName → email, name.formatted → displayName).
6. Assign users or groups in the IdP to the Vanta SCIM app to trigger initial provisioning.
7. Validate that users appear in Vanta's People list with correct attributes.

Watch out for: SCIM deprovisioning (setting active=false) marks the person as terminated in Vanta but does not delete the compliance history record. Test deprovisioning in a staging IdP group before rolling out broadly.

The people/users split is the most common source of integration errors: a script targeting /v1/users to deprovision an employee will appear to succeed but leave the compliance-tracked person record untouched, producing false coverage in audit evidence. OAuth tokens have expiry and require refresh logic; cached tokens will fail silently after expiration.

Cursor-based pagination is strictly sequential - parallel fetching with reused cursor tokens is not supported and will produce inconsistent result sets. SCIM setup requires both an active SSO configuration and an Enterprise plan; attempting to enable SCIM without SSO configured will fail at the Vanta settings layer before any API call is made.

For teams building identity graph pipelines across multiple tools, Vanta's externalId field (populated from connected HRIS or IdP integrations) is the reliable join key - email can drift across systems and should not be used as a primary correlation identifier in automated workflows.