Veza's SCIM 2.0 API enables automated user provisioning and management through your identity provider (IdP). This reference documents the API endpoints, request/response formats, and authentication requirements.

About This API

• Version: 2.0

• Base URL: https://{tenant}.vezacloud.com/scim/v2

• Protocol: HTTPS only

• Data Format: JSON

• Authentication: Bearer token

• Query Limit: 200 requests per minute

Compliance

This API implements the SCIM 2.0 protocol specifications:

• - SCIM Core Schema

• - SCIM Protocol

Resource Types

The API supports the following SCIM resource types:

Authentication

All API requests require authentication using a bearer token in the Authorization header:

API keys are generated in the Veza Administration console. See for details on creating and managing API keys.

Security Considerations

• Store and transmit API keys securely as they have administrative privileges

• All connections must use TLS 1.2 or higher

• SCIM API access should be restricted to your IdP's dedicated service account

Error Handling

The API returns standard HTTP status codes and a SCIM-compliant error response:

SCIM Endpoints

Important notes:

• All user management should be performed through your IdP once SCIM is enabled

• At least one admin user must exist on the root team as a break glass account

• Filtering operations are limited to equality (EQ) comparisons

Create Group

The displayName attribute is required for group creation.

Delete Group

Deleting a group removes it from Veza but does not affect the source group in your IdP.

List Groups

• Maximum of 200 groups returned per request

• Filtering is limited to equality operations (EQ)

Get Schema

Returns the SCIM schema definition supported by Veza.

Create User

Required attributes:

• givenName

• familyName

• userName (must match email address)

Additional requirements:

• Email attribute must be marked as primary

• Groups cannot be specified with group metadata

• When using SAML JIT, changing the email address may result in a new user being provisioned

List Resource Types

Returns the resource types supported by the SCIM implementation.

Get Users

Returns a list of provisioned users.

Patch Group

Only the following attributes can be modified:

• displayName

• members

• externalId

Patch User

Updates specific attributes of a user's metadata.

• Veza does not accept password changes

• When Veza receives an update for a local user account, the account is converted to an SSO account. Going forward, the user must sign into their SSO provider.

Update User

Replaces a user's metadata entirely. Note:

• Email attribute must be marked as primary

• SCIM-provisioned users cannot change their details in Veza

• Username must match email address

Get Service Provider Configuration

Returns the SCIM service provider configuration.

Delete User

Deactivates the user in Veza. User management should be performed through your IdP once SCIM is enabled.

This guide explains how to configure Okta as your identity provider (IdP) for secure, automated user provisioning with Veza. Following these steps will establish a connection between Okta and Veza for managing the complete user lifecycle including account provisioning and deprovisioning.

Notes on SCIM Provisioning

Veza supports the following SCIM provisioning features:

When using SCIM provisioning, Veza implements the following critical security behaviors that administrators should understand:

SCIM with SAML SSO: When SCIM provisioning is enabled in Veza Sign-In Settings, Veza no longer synchronizes user profiles during SAML logins (SAML JIT and SAML metadata sync is disabled).

Group-to-Role Mapping Behavior: Each unique push group from Okta is mapped to one or more team/role assignments in Veza. When a user is provisioned or their group membership changes, this role mapping is automatically applied to create or update the corresponding team/role assignments.

Permission Persistence: Users can receive the same permission from multiple IdP groups. Veza preserves permissions until all sources are removed. For example, if a user belongs to two different IdP groups that both assign Root/Admin roles in Veza, removing the user from only one of these groups will not revoke their Root/Admin permissions. The user will retain these permissions until removed from all groups granting access.

Prerequisites

To enable SCIM provisioning with Okta, you will need:

• Administrator access to both Veza and Okta

• An understanding of your organization's access control requirements

• HTTPS access to your Veza instance

You will need a dedicated local admin user in Veza for SCIM configuration, created during setup.

Important Considerations:

• At least one admin user must exist on the root team (break glass account)

• Once SCIM is enabled, all user management must be performed through Okta

• Okta User names must be the same as the user's email address

Enabling SCIM Provisioning with Okta

1. Create a SCIM Admin User in Veza

1. Go to Administration > User Management and create a new Veza user:

2. Assign the user to the root team with the following roles:

   • Admin is required for user management.

See for more on adding local user accounts to Veza.

2. Create an API Key and enable SCIM provisioning

1. Sign in as the newly created SCIM admin user

2. Navigate to Administration > API Keys

3. Create a new API key:

3. Configure Okta

1. In your Okta Admin Console, navigate to Applications > Applications

2. Click Create App Integration

3. Select SCIM as the sign-in method

4. Configure Group Push and Permissions

To log in to Veza, Okta users must be members of push groups assigned to the Veza application:

1. In Okta:

   • Create or identify the groups that will be used for Veza access

   • Assign users to these groups

See for more about pushing existing Okta groups with SCIM.

In Veza:

• Verify provisioned groups appear on the Administration > Team Management page

• For each team:

  1. Click on the team to view details

Team and role assignments determine user permissions within Veza. See for more information.

Groups are shown in Veza under the SAML configuration details. Click "Configure" on the Administration > Sign-in Settings page to view the pushed groups:

5. Role Management in Okta

When using SCIM provisioning with Veza:

1. You can use your existing Okta groups for provisioning users and teams to Veza.

2. For proper role assignment, ensure the groups pushed through SCIM match the groups configured in your Veza SSO settings:

   • Navigate to Administration > Sign-in Settings in Veza

Validation

1. in Okta, test the connector configuration:

   • Click Test Connector Configuration for the app integration

   • Verify the successful connection:

User Deprovisioning

To remove users from Veza:

1. In Okta:

   • Remove the user from all pushed groups

   • Unassign the user from the Veza application

To remove groups:

1. In Okta:

   • Remove the group from the SCIM application's Push Groups tab

Troubleshooting

Users or Groups not syncing

• Verify the user is assigned to the Veza application in Okta

• Confirm user is a member of at least one pushed group

• Check user's email matches their username

API authentication failures

• Verify the API key is correctly copied to Okta

• Confirm that SCIM is enabled on the Veza Sign-in Settings page.

• Ensure your Veza instance is accessible via HTTPS

Getting help

For additional assistance, please contact Veza Support and provide the following information if available:

• Okta System Log and Dashboard Tasks entries

• Veza error messages

• Timeline of the issue

• Steps to reproduce

Overview

Veza's SCIM API provides a powerful automation tool to manage user access throughout the identity lifecycle. When an employee joins, changes roles, or leaves your organization, these changes can automatically propagate to Veza, maintaining access control while reducing administrative overhead.

The SCIM (System for Cross-domain Identity Management) protocol is an open standard for automating user provisioning between identity providers and applications. Veza exposes a standards-compliant SCIM 2.0 API at https://{tenant}.vezacloud.com/scim/v2.