Overview

Use CSV Upload to integrate identity and authorization metadata from sources that don't have built-in Veza connectors, but can export or provide data in tabular format.

You can create a CSV integration in Veza to:

• Import user and authorization data from legacy or custom applications

• Integrate with SaaS applications that support CSV exports

• Model employee access to homegrown or specialized systems

• Upload employee metadata from your HRIS as a source of identity for Lifecycle Management workflows

The integration uses the Open Authorization API (OAA) to map CSV data to supported OAA templates:

• Application - Models Users, Groups, Roles, and Resources across applications for a wide variety of authorization use cases. An introduction to the Application Template .

• Human Resource Information Systems (HRIS) - Models employee information from HR sources for use with Lifecycle Management (LCM).

Application Template - Use Custom Applications to model business applications and access permissions:

• Models Users, Groups, Roles, and Resources across applications

• For example, you can upload user permissions from a homegrown CRM system, data store, or any other application users can access.

HRIS Template - Use for employee data from HR systems

• Models employee information and organizational structure

• For example, you can upload employee data for manager-based Access Reviews and automated provisioning with Lifecycle Management.

CSV integration is ideal for systems that export tabular data but lack dedicated Veza connectors:

• Legacy applications with user permission exports

• Custom business applications built in-house

• HR systems for employee lifecycle management

• Specialized industry tools without native APIs

CSV import enables modeling identity and permissions metadata for any application not natively supported by Veza, with flexible column mapping, custom properties, and support for multiple data formats.

To create an integration from CSV, you will need:

• A CSV file containing relevant data with column headers

• Sufficient permissions in Veza (Admin or OAA CSV Manager role)

• Understanding of the data model for the source application

For more information about user roles and permissions, see .

CSV (Comma-Separated Values) is a widely used file format that stores tabular data in plain text. Each row represents a record or a relationship between entities (e.g., User to Role), and columns represent attributes.

When importing from CSV:

1. The first row must contain column headers

2. Each column can be mapped to a specific Veza attribute or custom attribute

3. Columns can be ignored after uploading the file

4. At minimum, you must map columns for unique identifiers (such as user ID or Name) for each entity type you plan to import (e.g., Users, Groups, Roles, or Employees).

To create a new CSV integration:

1. Go to Integrations > Add Integration

2. Choose Upload CSV from the options

3. Upload a logo for the provider (optional) - This will appear throughout the Veza UI, including in Graph search, to identify the integration and entity types.

The CSV integration allows you to map columns in your file to specific Veza attributes. After uploading the CSV, Veza automatically detects all columns and presents them for mapping.

For each column, you can:

1. Select to include or exclude the column

2. Select the target entity type for mapping (available entities depend on the selected template)

3. Select the specific entity attribute to map to (only attributes applicable to the selected entity type will be shown)

Example: Mapping CSV columns to Application template entities and attributes

For more examples and detailed mapping patterns, see .

Additionally, you can apply to column data for more flexibility and additional formatting. Transformations can be used to:

• Combine columns to form a single attribute (e.g., first_name and last_name into a display name)

• Reformat data such as dates, times, and case (uppercase, lowercase)

• Apply padding, trimming, and character replacement

For all entities, an ID or Name is required. If ID is not provided, Name is automatically used as the unique identifier for the entity. Both are also supported.

The available entity types and attributes depend on the template you select. Each template supports different entity types.

Application Template Entities

User Attributes

Group Attributes

Role Attributes

HR System Template Entities

Employee Attributes

The following values are treated as TRUE (case-insensitive):

• true, t

• yes, y

• 1

Any other value is treated as FALSE.

Veza supports multiple timestamp formats:

• 2023-04-12T15:34:56.123456789Z (RFC3339 with nanoseconds)

• 2006-01-02T15:04:05Z07:00 (RFC3339)

• 20060102150405 (Active Directory format)

Timestamps are considered unset when the value is never, null, none, false, 0 or empty. Invalid timestamps will result in a processing error.

For attributes that support lists (like Role Name List, and Group Name List), values should be comma-separated within the cell and the list enclosude by quotes ".

Incremental updates are not supported; you must submit the complete data set for each update.

1. Find the CSV integration on the Veza Integrations page

2. Click on the integration name to view details

3. Under Data Sources, click Upload CSV

1. Find the CSV integration on the Veza Integrations page

2. Click on the integration name to view details

3. Click Edit

CSV integrations can send notifications about file upload and extraction status, and a Query Results Refreshed summary of how the risk-scored queries affected by an upload re-evaluate once it completes. Configure notifications on the Notifications tab when creating or editing a CSV integration.

For the available triggers, delivery options, recipients, message content, and REST API configuration, see .

Veza provides a limited privilege "CSV Manager" role for users that need permission to manage a CSV integration, but should not have access to other functionality in Veza.

Users with this role can:

• Create new CSV integrations

• Upload new CSV data

• Edit existing CSV integrations, including delete

This role can be combined with to further limit a user's scope. When a user with the CSV manager role is added to a non-root team, they can only manage CSV integrations assigned to their team.

• Multiple Rows per Entity: If the same entity (user, group, or role) appears in multiple rows, Veza processes them as follows:

  • Properties are set based on the first row where the entity ID (or Name if it is being used as the unique ID) appears

  • For subsequent rows with the same identifier, only relationship assignments are processed (for example user to group, or user to role)

Overview

In addition to using a simple web interface to update CSV data manually, you can automate a process to push new data using the Veza REST API and refresh the Veza graph. This document includes example utilities using Python and CLI tools.

Using the Upload CSV REST API

After creating a CSV upload integration, you can use the REST API operation Push Custom Provider Datasource CSV to upload new CSV data.

Whenever a CSV is submitted, it is processed based on the current configuration of the CSV Upload Integration provider, including any column mapping settings.Authentication: To make API calls, you must include an authorization token in the header of each request. This can be:

• A Personal API Key for a Veza administrator

• A Team API Key, for a team assigned to manage CSV Upload integrations

See for more details on creating API keys.

Note: The CSV data must be complete for each upload. Veza will remove entities from the Graph for any entities that were present in the previous upload, but not in the current upload.

Using the REST API requires the Integration (Provider) and Data Source IDs. You can retrieve these in Veza on the Integration Details > Data Source tab:

1. On the Veza Integrations page, click the CSV integration to view details

2. On the Data Source tab, click the data source name to view details

3. Copy the values from the Properties table:

Uploading the CSV data is made with a post call to the /api/v1/providers/custom/{provider_id}/datasources/{data_source_id}:push_csv endpoint.

Note: The CSV contents must be base64-encoded into the JSON body of the request. Raw CSV values are rejected. You can automatically convert the data as part of your implementation, as shown below.

When mapping CSV columns to Veza attributes, you can apply transformations to format, combine, or convert data during import. This enables data standardization without requiring modifications to source CSV files.

Transformations are useful for:

• Combining columns into a single attribute (e.g., display name from first and surname)

• Reformatting dates or times to match expected formats

This document helps you identify and resolve common issues when importing CSV files into Veza.

Understanding CSV Import Behavior

Before troubleshooting, it's important to understand how the CSV import process works:

File Requirements

• Maximum file size: 100MB per CSV file

• Character encoding: UTF-8 recommended

• First row: Must contain column headers

• Column delimiters: Commas

• Text qualifiers: Double quotes for fields containing commas

• Users: Each user must have either an id or name (or both)

• Groups: Each group must have either an id or name (or both)

• First-row behavior: For entities appearing in multiple rows, only the first row sets the entity properties

• Subsequent rows: Additional rows with the same identifier only process group and role assignments

• Role permissions: Permissions for the same role are added across all rows (additive)

1. Start with a test file

   • Begin with a small subset of data to verify your mapping configuration

   • Test with representative examples of your data structure

Be aware of these current limitations in the CSV import functionality:

1. No application resources support

   • Resources within applications are not currently supported

2. No direct user-to-permission mapping

If you continue to experience issues after reviewing this guide:

1. Review the for details on supported formats and mapping options

2. Check the for guidance on structuring your CSV files

3. Contact Veza Support with:

The CSV Upload integration supports notifications to inform subscribers about the status of file uploads and how queries affected by the upload re-evaluate once processing completes.

Notifications are opt-in and configured on the Notifications tab when creating or editing a CSV integration.

Two distinct categories of notification are available:

• Upload and extraction status — progress and outcome of receiving and processing an uploaded file.

• Query Results Refreshed — a summary of how the risk-scored queries affected by the upload were re-evaluated, and whether their results are reflected in the latest risk scores.

You can configure notifications for the following Veza Action integrations:

• Email: No additional configuration required.

• Slack App: Requires the to be configured.

• Microsoft Teams App: Requires the to be configured.

Subject and body are identical across email, Slack, and Microsoft Teams; only channel-specific formatting differs.

• Integration Owners: Notify the users assigned as , not only its creator. Owners can be users or groups; only owners that resolve to a user with an email address are notified.

• Additional Recipients: One or more email addresses, separated by commas.

A notification is only sent when at least one delivery option, one trigger, and one recipient are selected.

These notifications report progress as Veza receives and processes an uploaded file.

Veza polls upload status for up to 24 hours after the file is received to detect extraction events.

These messages are not customizable. Veza sends a fixed subject and body for each trigger, substituting the uploaded file name. For failures, the underlying error message is appended to the body.

Example messages for an uploaded file named employees.csv:

Enable this notification with the Query Results Refreshed checkbox in the integration's notification preferences.

After a CSV upload finishes processing, Veza re-evaluates the queries that depend on the uploaded data and refreshes their results, including any risk scores. The Query Results Refreshed notification summarizes the refresh for the latest risk-score cycle.

Query evaluation and risk-score evaluation run on separate, environment-configurable schedules (typically hourly and daily). The notification is sent once, after the first risk-score evaluation following the upload. If that evaluation does not run before Veza's timeout, the notification is sent anyway, with a subject noting that risk scores were not updated.

Only the queries that the upload could actually change are summarized. A query is included when all of the following are true:

• It has an assigned . Queries without a risk level are not refreshed.

• It is enabled. Disabled and hidden queries are excluded.

• Queries that the upload cannot affect are skipped.

The notification groups the included queries into three lists, based on whether each query finished in time to be reflected in the latest risk-score cycle:

The message shows a count of successful queries (for example, "12 of 14"), a combined count of failed or incomplete queries, and the query names in each group. The successful-query list is truncated after 15 entries, ending with a trailing - ....

The subject reflects the combined outcome and names the uploaded file:

The body opens with the outcome line, then a short note, the counts, and the queries in each group:

Notifications can be configured via REST API by setting the notification_preferences field on the custom provider when or updating an integration.

Example notification_preferences block:

• subscribed_events: FILE_RECEIVED, EXTRACTION_IN_PROGRESS, EXTRACTION_COMPLETED, EXTRACTION_FAILED, FILE_RECEIVE_FAILED, FAILURE (subscribes to all failure events), or QUERY_RESULTS_REFRESHED.

• — create and configure a CSV integration.

• — set up Slack and Microsoft Teams delivery.

This document provides practical examples for mapping data from CSV files into Veza using the integration.

You can use the CSV integration to flexibly model user, group, and role relationships based on data exported from the source application. This document includes examples from basic user data import to modeling more complex organizational structures, which you can adapt based on your needs.