APIs for automating user and group provisioning.
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.
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:
The API supports the following SCIM resource types:
Users
Individual user accounts
/Users
Groups
User groups mapped to Veza Teams
/Groups
Schemas
Resource type definitions
/Schemas
ServiceProviderConfig
Service provider configuration
/ServiceProviderConfig
ResourceTypes
Available resource types
/ResourceTypes
All API requests require authentication using a bearer token in the Authorization header:
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
Dates use ISO 8601 format
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)
displayName
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 into 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
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.
Returns the SCIM service provider configuration.
Deactivates the user in Veza. User management should be performed through your IdP once SCIM is enabled.
- SCIM Core Schema
- SCIM Protocol
API keys are generated in the Veza Administration console. See for details on creating and managing API keys.
Step-by-step guide for configuring automated user provisioning between Okta and Veza using SCIM 2.0.
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.
Veza supports the following SCIM provisioning features:
Push New Users
Users assigned to the Veza application in Okta are automatically created in Veza
Push Profile Updates
Profile changes in Okta are automatically updated in Veza
Push Groups
Groups assigned to the Veza application in Okta are automatically created as Teams in Veza
Deactivate Users
Removing users from the Veza application in Okta automatically deactivates them in Veza
Reactivate Users
Reassigning previously deactivated users in Okta reactivates them in Veza
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.
Ensure you maintain at least one local admin account on the root team as a break glass account. This account provides access if there are issues with your identity provider connection.
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
Veza creates Teams from groups provisioned through SCIM. Permissions are managed by assigning roles to teams provisioned in Veza.
Go to Administration > User Management and create a new Veza user:
Assign the user to the root team with the following roles:
Admin is required for user management.
Check your email for "Welcome to Veza.com" and reset the password
Sign in as the newly created SCIM admin user
Navigate to Administration > API Keys
Create a new API key:
This is a personal API key for the SCIM admin user
Save this key securely using your organization's secrets management process; this key has administrative access to your Veza instance
The key cannot be retrieved after creation
Go to Administration > Sign-in Settings
Scroll down and check the box to Enable SCIM provisioning
Note: There is a 30-second delay before endpoints become available
In your Okta Admin Console, navigate to Applications > Applications
Click Create App Integration
Select SCIM as the sign-in method
Configure the app with the following settings:
Base URL: https://TENANT.vezacloud.com/scim/v2
Unique identifier field for users: userName
Supported provisioning actions:
Push New Users
Push Profile Updates
Push Groups
Deactivate Users
Authentication Mode: HTTP Header
Authorization: Your Veza API key from Step 2 "Create an API Key and enable SCIM provisioning"
To log in to Veza, Okta users must be members of push groups assigned to the Veza application:
In Okta:
Create or identify the groups that will be used for Veza access
Assign users to these groups
Navigate to your Veza application
Select the Push Groups tab
Add the groups you want to provision to Veza
In Veza:
Verify provisioned groups appear on the Administration > Team Management page
For each team:
Click on the team to view details
To change roles for a user, click Change Roles in the Actions column.
To change the team scope, click Edit and add or remove providers, then save your changes.
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:
You can use your existing Okta groups for provisioning users and teams to Veza.
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
Review the "Role Mapping" section to verify your group-to-role mappings
To add permissions to teams:
Navigate to Administration > Team Management in Veza
For each team:
Click on the team to view details
To change roles for a user, click Change Roles in the Actions column
To change the team scope, click Edit and add or remove providers, then save your changes
To assign Veza roles directly to individual users using the Roles attribute in Okta:
In Okta Admin Console, navigate to your Veza application
Under Provisioning > To App, click Edit
In the Attribute Mappings section, add the following:
Okta Attribute: roles
Veza Attribute: roles
Available roles:
admin
viewer
operator
scim_provisioner
Note that direct role assignments can only be set for individual users (not groups).
in Okta, test the connector configuration:
Click Test Connector Configuration for the app integration
Verify the successful connection:
Verify user provisioning:
Assign a test user to the Veza application and a pushed group
Wait 2-3 minutes for synchronization
Confirm the user appears in Veza under Administration > User Management
Verify the account's attributes match the Okta user.
Verify group provisioning:
Confirm Okta groups appear as Teams in Veza
Verify that team membership matches the group membership in Okta
Test that assigning roles to teams functions as expected
Test security boundaries:
Attempt to sign in with a deprovisioned user to verify access is properly removed
Verify that removing a user from one group but not another maintains appropriate permissions
Confirm that users cannot access Veza directly (bypassing SCIM/SAML) once integration is complete
To remove users from Veza:
In Okta:
Remove the user from all pushed groups
Unassign the user from the Veza application
In Veza:
The user should appear as deactivated
The user cannot log in
The user's API keys are disabled
To remove groups:
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
Review Okta System Log for provisioning errors
Confirm group push is enabled in the application settings
In Okta, verify the group is added to the Push Groups tab for the Veza app
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
Automate user lifecycle management from your Identity Provider (IdP) with user and group provisioning through SCIM 2.0.
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.
Veza supports SCIM 2.0 integration with:
Microsoft Entra ID (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:
Create a dedicated admin user in Veza with SCIM Provisioner privileges
Generate and securely store an API key for your identity provider to authenticate
Enable SCIM provisioning in Veza's administration settings
Configure your identity provider with Veza's SCIM endpoint and authentication details
Enable push groups to align identity provider groups with Veza teams and roles
Validate the integration by testing the full provisioning lifecycle
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 Provisioner is required to access Veza SCIM endpoints.
See for more on adding local user accounts to Veza.
See for more about pushing existing Okta groups with SCIM.
Team and role assignments determine user permissions within Veza. See for more information.
For details on SSO role mapping, see .
See for more information on team management.
For identity provider-specific instructions, follow our detailed guide for .
- SCIM API endpoints and schema documentation
- Create and manage API keys
- Configure SAML SSO
- More information about Veza teams and role assignments
Deletes a specific Veza group by id
A unique request id used for tracing and debugging purposes.
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
No content
Retrieves a list of Veza groups
A unique request id used for tracing and debugging purposes.
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
No content
Returns the schema definitions supported by Veza including all attributes,
their mutability, returned status, uniqueness, and type information.
A unique request id used for tracing and debugging purposes.
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
No content
Returns the types of resources available in Veza's SCIM implementation (Users, Groups).
Each resource type includes the endpoint, schema URI, and supported operations.
A unique request id used for tracing and debugging purposes.
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
No content
Retrieves a list of Veza users. Supports filtering, pagination and sorting.
A unique request id used for tracing and debugging purposes.
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
No content
Returns SCIM protocol features supported by Veza, including authentication
schemes, patch support, bulk operations capability, and filtering features.
A unique request id used for tracing and debugging purposes.
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
No content
Deletes a specific Veza user by id
A unique request id used for tracing and debugging purposes.
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
No content
Creates a new Veza group in the system
A unique request id used for tracing and debugging purposes.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
No content
Creates a new Veza user in the system.
A unique request id used for tracing and debugging purposes.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
No content
Updates an existing Veza group's attributes using patch operations
A unique request id used for tracing and debugging purposes.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
No content
Updates an existing Veza user's attributes using PATCH operations.
Supports operations: add, replace, remove
A unique request id used for tracing and debugging purposes.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
No content
Replaces an existing Veza user with a new profile
A unique request id used for tracing and debugging purposes.
startIndex: 1-based index of the first result to return (default: 1)
count: Maximum number of resources to return (default: server-determined)
filter: SCIM filter expression (e.g. "userName eq "john@example.com"")
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
No content