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.

Supported identity providers

Veza supports SCIM 2.0 integration with:

• Okta

• (formerly Azure AD)

Before implementing SCIM provisioning, ensure you understand the prerequisites and process flow. This integration requires administrator access to both Veza and your identity provider, as well as a dedicated service account for secure API communication.

The implementation follows these key steps:

1. Create a dedicated admin user in Veza with SCIM Provisioner privileges

2. Generate and securely store an API key for your identity provider to authenticate

3. Enable SCIM provisioning in Veza's administration settings

4. Configure your identity provider with Veza's SCIM endpoint and authentication details

For identity provider-specific instructions, follow the detailed guide for .

SCIM requests authenticate with an API key belonging to a principal that has the SCIM Provisioner role. See in the SCIM API Reference.

When enabling SCIM, there are some critical behaviors to be aware of:

• SAML and SCIM interaction: When you enable SCIM provisioning, Veza automatically disables SAML Just-in-Time (JIT) provisioning to prevent potential conflicts. User profile updates now come exclusively from your identity provider through SCIM.

• Group-to-role mapping: Veza maps each identity provider group to one or more team/role assignments in Veza. When a user's group membership changes in your IdP, Veza automatically updates their team/role assignments.

• Permission persistence: If a user has the same permission from multiple groups, that permission remains until you remove the user from all groups granting that access. For example, if a user belongs to two groups that both assign Admin roles, removing them from only one group will not revoke their Admin permissions.

• - SCIM API endpoints and schema documentation

• - Create and manage API keys

• - Configure SAML SSO

• - More information about Veza teams and role assignments

This guide explains how to configure Microsoft Entra ID as your identity provider (IdP) for automated user provisioning with Veza. Following these steps will establish a connection between Entra ID 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 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 Entra ID 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.

To enable SCIM provisioning with Entra ID, you will need:

• A Microsoft Entra subscription with permission to create enterprise applications

• Entra ID SAML SSO with Veza already configured. SCIM provisioning requires a SAML auth provider connection in Veza. See for setup instructions. Note: SCIM provisioning uses a separate non-gallery enterprise application in Entra ID; keep your existing SSO application in place.

• Administrator access to Veza

• 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 Entra ID

• userName must match the user's primary email address. Veza validates that the SCIM userName and the primary emails value are identical. Configure Entra ID to send userName

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 or Operator is required to log in and create a personal API key. This role can be revoked after the API key is obtained.

See for more on adding local user accounts to Veza.

1. Sign in as the newly created SCIM admin user.

2. Navigate to Administration > API Keys.

3. Create a new API key:

   • This is a personal API key for the SCIM admin user.

1. In the Microsoft Entra admin center, go to Entra ID > Enterprise applications.

2. Click New application, then select Create your own application.

3. Enter a name (for example, "Veza SCIM"), select Integrate any other application you don't find in the gallery, and click Create.

1. Under Settings, set Scope to Sync only assigned users and groups. This limits provisioning to users and groups explicitly assigned to the application, avoiding unintended account creation.

2. Expand Mappings and open the Provision Microsoft Entra ID Users mapping.

3. Review the attribute mappings. The following attributes are required:

1. In the application, select Users and groups.

2. Add the Entra ID groups and users to provision to Veza.

3. Return to Provisioning and set Provisioning Status to On, then save.

After enabling provisioning, Entra ID runs an initial sync cycle immediately, then syncs on a 40-minute interval. See for more details on the provisioning cycle.

Groups provisioned via SCIM appear as Teams in Veza under Administration > Team Management. Groups do not automatically carry Veza role assignments; you must configure role mappings in Veza separately.

To assign roles to provisioned groups:

1. In Veza, navigate to Administration > Sign-in Settings.

2. Click Configure on your SAML connection.

3. In the Role Mapping section, add a mapping for each Entra ID group that should receive a Veza role.

See and for more information.

1. In Entra ID, go to Provisioning > Provision on demand, select a test user, and run a provisioning cycle.

2. Review Provisioning logs for success or error details.

3. In Veza, verify the test user appears under Administration > User Management with the correct name and email address.

To remove users from Veza:

1. In Entra ID:

   • Unassign the user from the Veza application, or disable or delete the account.

2. In Veza:

   • The user will appear as deactivated.

To remove groups:

1. In Entra ID:

   • Remove the group assignment from the application.

• Check Provisioning logs in Entra ID for specific error messages on each user.

• Verify the user is assigned to the application and is a member of an assigned group.

• Confirm that userName maps to the user's email address. This is the most common provisioning rejection.

Entra ID is sending a userPrincipalName that is not in email format. Update the Entra ID attribute mapping to send mail as userName instead of userPrincipalName.

Entra ID may send a PATCH operation updating the displayName attribute during profile sync. Veza does not support patching displayName directly and returns a 400 error for this operation. Veza derives the display name from givenName and familyName. To prevent this, remove any displayName attribute mapping from the Provision Microsoft Entra ID Users mapping in Entra ID.

• Verify the API key was copied correctly into the Secret Token field.

• Confirm the SCIM admin user's API key has not expired or been revoked.

• Ensure your Veza instance is accessible via HTTPS.

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

• Entra ID provisioning logs

• Veza error messages

• Timeline of the issue

• Steps to reproduce

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.

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

• An Okta version that supports SCIM 2.0

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

• Queries are limited to returning a maximum of 200 items at a time

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.

   • SCIM Provisioner

See for more on adding local user accounts to Veza.

1. Sign in as the newly created SCIM admin user

2. Navigate to Administration > API Keys

3. Create a new API key:

   • This is a personal API key for the SCIM admin user

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 the app with the following settings:

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

   • Navigate to your Veza application

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

  2. To change roles for a user, click Change Roles in the Actions

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:

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

   • Click "Configure" on your SAML connection

1. in Okta, test the connector configuration:

   • Click Test Connector Configuration for the app integration

   • Verify the successful connection:

To remove users from Veza:

1. In Okta:

   • Remove the user from all pushed groups

   • Unassign the user from the Veza application

2. In Veza:

To remove groups:

1. In Okta:

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

• 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

• Review Okta Dashboard Tasks for provisioning errors

• 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

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

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

This API implements the SCIM 2.0 protocol specifications:

• - SCIM Core Schema

• - SCIM Protocol

The API supports the following SCIM resource types:

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

Use an belonging to a user or team service account that has the SCIM Provisioner role, and send the key as the bearer token. Identity provider integrations, such as the and guides, use this method.

• 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

• You can implement monitoring using Veza APIs or event subscriptions for unexpected provisioning or deprovisioning activities

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

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

• Error responses follow the SCIM error schema

The displayName attribute is required for group creation.

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

• Maximum of 200 groups returned per request

• Filtering is limited to equality operations (EQ)

Returns the SCIM schema definition supported by Veza.

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

Returns the resource types supported by the SCIM implementation.

Returns a list of provisioned users.

Only the following attributes can be modified:

• displayName

• members

• externalId

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 in to their SSO provider.

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

• The request cannot include groups information

Returns the SCIM service provider configuration.

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