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:

• Microsoft Entra ID (formerly Azure AD)

Enabling SCIM provisioning

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 our detailed guide for .

Important notes for SCIM Provisioning

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 User Lifecycle Automation Flow

Additional resources

• - SCIM API endpoints and schema documentation

• - Create and manage API keys

• - Configure SAML SSO

• - More information about Veza teams and role assignments

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

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

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

• Error responses follow the SCIM error schema

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

• The request cannot include groups information

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

• 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

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.

   • SCIM Provisioner is required to access Veza SCIM endpoints.

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:

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

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

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

   • 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 column.

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

   • Click "Configure" on your SAML connection

Validation

1. in Okta, test the connector configuration:

   • Click Test Connector Configuration for the app integration

   • Verify the successful connection:
2. Verify user provisioning:

User Deprovisioning

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

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

• Review Okta Dashboard Tasks for provisioning errors

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