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

Retrieving Integration IDs

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:

   1. The unique data source "Id"

Uploading the Data

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.

Example using Curl

Example using Python

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

Entity Requirements

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

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

• Roles: Each role must have either an id

Processing Rules

• 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)

• All properties: All properties (including custom properties) are set only from the first row where that entity appears

Common Issues and Solutions

Configuration and Integration Issues

Mapping Issues

Data Format Issues

List Column Issues

Preparation Best Practices

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

2. Validate CSV format

Current Limitations

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

   • Permissions must be assigned to roles, which are then assigned to users

Getting Support

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:

   • A sample of your CSV file (with sensitive data removed)

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.

When to Use CSV Integration

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.

Adding a CSV Integration

Prerequisites

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

• A plan for mapping between CSV columns and Veza attributes

For more information about user roles and permissions, see .

Format Requirements

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).

Create a CSV Integration

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.

4. Enter an integration name

CSV Column Mapping

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)

4. For custom properties, specify a name and data type

Example: Mapping CSV columns to Application template entities and attributes

For more examples and detailed mapping patterns, see .

Supported Entity Types and Attributes

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

Data Type Handling

Boolean Values

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

• true, t

• yes, y

• 1

Any other value is treated as FALSE.

Timestamp Formats

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.

String Lists

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 ".

Updating a CSV Integration

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

Push new data for an existing integration

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

4. Select your updated CSV file and click Upload

Update mappings for an integration

1. Find the CSV integration on the Veza Integrations page

2. Click on the integration name to view details

3. Click Edit

4. In the integration configuration, click Edit above the table of current mappings

CSV Manager Role

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.

Processing Rules

• 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)

  • Role permissions are the only properties that are additive across all rows

Related Documentation

This document provides practical examples for mapping data from CSV files into Veza using the CSV Upload 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.

• CSV Upload Examples

  • Mapping Concepts

Mapping Concepts

When importing CSV data into Veza, you are typically establishing one or more of these key components:

1. Entities: Users, groups, and roles that exist in your application

2. Attributes: Properties that describe each entity (e.g., name, email, status)

3. Relationships: Connections between entities (user belongs to group, user has role)

The examples below demonstrate different approaches to mapping these components from CSV data into Veza's Access Graph.

Basic User Mapping Example

For a simple file containing user records, one user per row with a list or groups and roles. You can map columns directly:

Example CSV:

Your CSV files may have column names that differ from Veza's standard attribute names.

Group and Role Assignment Methods

The CSV integration supports two methods for assigning users to groups and roles:

Method 1: Using List Columns

Use a single column containing comma-separated values to assign a user to multiple groups or roles at once.

Column mapping:

Example CSV:

Key points about list columns:

• Values must be comma-separated

• Enclose lists in quotes if they contain commas

• Whitespace around values is automatically trimmed

• Empty values are ignored

Method 2: Using Multiple Rows Per User

You can incrementally assign roles or groups using multiple rows with the same user id. This approach is useful when:

• You have many groups or roles per user

• Your source system exports data in this format

• You need to include additional details for roles or groups such as custom properties

Example CSV:

Key points about multiple row assignments:

• The first occurrence of an entity id sets all properties for that entity. If the same user or role is listed more than once, the user or role attributes are not updated for rows after the first.

• Subsequent rows only process new group and role assignments

Advanced Role Permissions

The CSV can include a column with a list of permissions for each role. This enables searching and filtering by permission in Veza:

You can assign permissions to roles and then users to roles:

Note: If permissions column is not defined any Roles are automatically assigned the Member permission

Real-World Example: Complex Organization Structure

This example shows how to represent a complex organizational structure with departments, teams, roles with permissions, and user assignments:

Column mapping for this example:

This example CSV will create:

• 7 user entities with their properties

• Department groups (Engineering, Product, Marketing, Finance, HR, Sales)

• Team groups (Backend, Architecture, Frontend, Product Management, UX Research, Content, Social, Accounting, Recruiting, Enterprise Sales)

• Multiple role assignments per user

Supported Timestamp Formats

The CSV integration supports various timestamp formats:

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

Boolean Value Handling

When mapping to boolean attributes like is_active:

• TRUE values: true, t, yes, y, 1, active, enabled

• FALSE values: Any other value including false, f

Custom Properties Example

Any column can be mapped to a custom property for any entity type. When mapping to a custom property:

1. Select Custom Property as the attribute

2. Enter a name for the custom property

3. Select the data type (String, Number, Boolean, Timestamp, or String List

Entity Owner Example

Designated Entity Owners can up supplied for supported Application entity types as part of the CSV. This allows for automatically assigning the owner from the value in the CSV.

This example indicates the owner of the Role and could be used auto-assign Access Review rows to the owner for each role.

Note that when a is configured, Owner Type is optional. Otherwise, the owner type is used to specify the type of entity in Veza Graph that will be assigned as an owner. This will typically be a User entity in your organization's Identity Provider (such as an Okta, Azure AD User, or Active Directory User), representing a top-level human identity.

For more information about Entity Owners, see: