All pages
Powered by GitBook
1 of 49

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Best Practices

Strategies and best practices for OAA connector development

See the included topics for more information about developing an Open Authorization API connector.

  • Connector Requirements

  • Using OAA Templates

  • Providers, Data Sources, Names and Types

Sourcing and Extracting Metadata
Naming and Identifying OAA Entities
Modeling Users, Permissions, and Roles
Custom Properties
Tagging with OAA
Cross Service IdP Connections

Providers, Data Sources, Names and Types

Naming, typing, and searching for top OAA entities

Custom providers and data sources

Before uploading entity metadata for an OAA integration, you must create a custom provider and at least one data source under that provider. The provider represents the type of application (such as "Jira Server") and determines the template used for all data sources (e.g."dev", "prod")created under that provider.

The OAA payload is pushed to a specific data source and updates the existing data.

A display icon can be set for the provider, shown throughout the Veza UI to identify the integration and its entities.

Naming the provider and data source is an important step in integration creation. In general,

  • The provider name should be unique to the integration. Avoid common terms such as "application". Separating providers for systems with several instances such as "production" and "development" can be a good idea.

  • The provider or data source value should be unique to the integration and incorporate an identifier such as hostname or other instance ID. This ensures that multiple instances of the integration can be separated if necessary.

  • Do not user random or date values in provider or data source names. Each run of the connector should result in the same provider and data source name, based on discovered values or a configuration parameter.

Each OAA Template supports a concept of name and type. The type enables search for all instances of a specific entity. For example, the Application Type identifies application entities such as users, groups, roles, and resources. It will enable search for all entities in an application. Setting the application type to Widget will allow for search Widget Users, Widget Groups, and other entity types:

The app name appears when searching for individual entities, and, to differentiate more than one instances of the same system. For example two instances of an application "Widget - Production" and "Widget - Stagging".

Custom application names and types

App Type Search

Naming and Identifying OAA Entities

Setting unique identifiers and human-readable names using OAA templates

Veza requires each entity to have a unique identifier, used within the template to reference entities (which groups a user is a member of) and for Veza to use to track and display the entity. This is true for both the Application and IdP templates

By default the templates use the name field for this purpose. However, names are not unique within some applications. In this case the templates offer an optional id as a unique identifier, allowing name to function as a non-unique display name.

Custom Application

Local User, Local Group and Local Role have an optional value id that can be provided for each entity that serves as the unique identifier.

  • To use id all Local Users, Local Groups and Local Roles must be defined with an ID. The name and id can be the same value as long it is unique for the entity type. For example a local role can have admin for both the name and id.

  • The id value becomes the key for referencing local users, groups and roles in the identity_to_permissions section of the payload and for referencing group memberships.

Using ids for mapping, instead of name is recommended in most cases, especially if any of the following are true:

  • Entity names aren't unique in the application (if two users can have the name "Joe Doe" but each have a unique user id such as email or login or the applications unique id).

  • The API references users, resources, and other entities by an ID instead of name. Using the same ID for the OAA payload will limit scenarios where you need to maintain a mapping of id to name in your connector.

For Custom Application to use id for Local Users, Groups and Roles all entities must use the id field. To use the id field for Resources all Resources and Sub-Resources must have an id

Resources and Sub-resource each can have an optional id value. When provided, the resource name does not need to be unique. To use id, all resources and sub-resources must be defined with a unique ID. The id value will be used to assign resource permissions in identity_to_permissions.

Custom IdP also supports a optional unique identifier value identity for Users and Groups. If not used, the entity name must be unique and will be the primary identifier.

Resources

Custom IdP

Tagging with OAA

Both custom properties and Veza Tags can be used to add rich metadata and apply labeling strategies across entities in the Veza Access Graph. Both can be viewed by checking an entity's details, and are fully available when searching and filtering results.

Veza tags can be assigned to objects in an OAA payload. One typical use case for tagging within the OAA payload is assigning resource managers with Veza SYSTEM_resource_managers tags.

Tags are applied by providing a key and an optional value for each. A new tag will be created if a matching one doesn't already exist.

{
  "resource_type": "Cluster",
  "description": "release staging cluster",
  "sub_resources": [],
  "tags": [
    {
      "key": "environment",
      "value": "development"
    }
  ]
}

Due to superior integration with other Veza functionality and ease of updates, custom properties are recommended as the best approach for adding metadata to OAA entities, unless tagging is required as part of a larger campaign.

Note that while tags can be removed using the Tags API, tags applied within the template are persistent: an existing tag won't be deleted when pushing a payload with a new tag or empty tag.

Modifying Tags with Incremental Updates

After the initial metadata push (which must contain the full payload), you can modify, add, or remove the domain, users, and groups without resubmitting other entities. An incremental update is enabled by setting "incremental_change": true in the json_data push payload, and specifying the update operation for each entity to change.

The operation field indicates the change to make. Valid operations are:

  • "add", "modify", "delete" to create, change, or remove an entity.

  • "add_tag", "delete_tag" to update a tag without altering the entity.

...
"local_groups": [
    {
      "name": "LGroup1",
      "identities": [
        "localgroup1@company.com"
      ],
      "tags": [
        {
          "key": "NewTag2Key",
          "value": "NewTag2Value"
        }
      ],
      "operation": "add_tag"
    }
]
...

Structures

Data structures supporting the OAA templates.

Case-insensitive collection types used to track entities such as local users, groups, roles and resources by name or unique ID.

Copyright 2026 Veza Technologies Inc.

Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.


class CaseInsensitiveDict

Case Insensitive Key Dictionary

Dictionary like object with case insensitive keys for types that support .lower() such as strings.

Keys do not have to be strings, in the case where the key type does not support .lower() such as integers the value is used as is.

Example: from oaaclient.structures import CaseInsensitiveDict >>> x = CaseInsensitiveDict() >>> x["User"] = "value" >>> x.get("user") 'value' >>> "USER" in x True >>> print(x) {'user': 'value'} >>> x CaseInsensitiveDict({'user': 'value'})

__init__(data=None, **kwargs) → None

method __init__

Sourcing and Extracting Metadata

Strategies for extracting authorization, identity, and resource metadata

When planning an OAA connector, consider how you will gather the information you want to import into Veza. Refer to the application’s documentation to confirm you can obtain the required metadata from the host application.

Ideally, you will be able to list and collect metadata for:

  • User records

  • Group memberships

  • User roles and permissions

  • Resource names and metadata

For example, the Veza-GitHub connector utilizes the following endpoints (in addition to basic authentication and authorization APIs):

Web-based APIs are a common solution for SaaS apps, but not required for an OAA integration. Just because an endpoint exists does not mean that it returns useful information (some APIs are more designed for client automation than audits). Possible choices for sourcing metadata include:

  • From a database: Is data for a hosted app available in a database your connector can query?

  • File-based extraction: is the metadata available in source code or a configuration file, or an exportable report (such as CSV)?

  • Other options: does the provider have an SDK or CLI interface you can use to retrieve data?

If no machine-readable data is readily available, even screen scraping could be a solution. There are many creative options for extracting the information to populate the template, although an API will typically be the most usable option.

- orgs/{org_name} - Get Organization information
- orgs/{org_name}/members - List members for an organization
- orgs/{org_name}/teams - List teams for an organization
- orgs/{org_name}/teams/{team}/members - List members for a given team
- orgs/{org_name}/repos - List organization repositories
- repos/{org_name}/{repo}/teams - List Team permissions for repository
- repos/{org_name}/{repo}/collaborators?affiliation=direct - List team members with direct permissions

Cross Service IdP Connections

Mapping OAA objects to external and federated identities

In Veza, the Identity Provider (IdP) serves as the representation of the source of an identity (human or otherwise). That identity can have access to many applications, clouds and other data sources. By connecting OAA entities to source IdP identities, Veza can show all the access for that identity. This can also enable powerful correlation queries such as finding deactivated Okta Users with active application accounts.

Veza makes these connections based on the identity information provided in the OAA payload.

Veza Supports Mapping for the following Identity Providers:

  • Active Directory

  • Azure AD

  • Custom IdP

  • Google Workspace

  • Okta

  • OneLogin

For all Identity Providers, the IdP Unique ID and email attributes are used to match the source identity to an OAA principal. Some entity types have additional properties usable for identity mapping:

  • Active Directory

    • Account Name

    • Distinguished Name

  • Azure AD

Comparison ignores case, and is otherwise an exact match on the whole value. Veza does not strip domains, ignore punctuation, or compare email aliases when resolving identities from a payload. For Google Workspace, the compared values are the primary email address only.

For the full per-provider attribute list, the attributes Veza does not compare, such as employee IDs, and guidance on identities that fail to resolve, see . To correlate on an attribute outside that list, configure a on the identity provider integration.

The Application Template's Local User entity represents a user within the application. That Local User can map to an Identity Provider (IdP) by setting the identity value(s) in the Local Users identities array. Veza will use these identities to create an association between the IdP Identity and the Local User.

The Local User's email property is a display attribute and is not compared. Populate identities even when the same address is already set in email.

Veza uses the first value in identities that resolves and creates one connection per Local User, so additional values act as alternatives rather than as additional connections. A Local User in the , used by several built-in connectors, connects to every identity that resolves.

Setting external IdP Group identities is also supported on Local Groups. This should be used when there are no Local User records in the application that correlate to the external user identities. Veza will create a connection between the IdP Group and the Local Group, indicating that all IdP users from that group will have the access granted to the Local Group.

Unknown identities set on users will result in a warning that the identity can not be found. The OAA Local User will still be successfully created.

Note on Identity Mapping from the IdP: You can confirm these values by finding the corresponding entity in Veza search or the data catalog and checking the identities Idp Unique Id and other fields in the details view. Identities that cannot be resolved are returned as warnings when the application payload is pushed.

For applications that use Okta for SSO, you can also enrich local users with last login timestamps from Okta activity data. Set okta_app_id on the application object to enable this enrichment — Veza uses the same identities values to match local users to their Okta profiles. See .

OAA Identity Provider Users can be connected to other IdPs by using the source_identity property on the IdP users. For details see

Veza correlates HRIS Employee records to IdP identities using one value per employee, taking the first of idp_id, email, and employee_number that is set. Set the optional idp_id when the value that identifies the employee in the IdP is not their email address. Veza then compares that single value against the IdP attributes listed above, so an employee_number correlates only when it is also the IdP login, principal name, or email address.

For details, see .

Principal Name
  • On Premises SAM Account Name

  • Okta

    • User Login

  • Application Template

    Identity Provider (IdP) Template

    Human Resources Information System (HRIS) Template

    Automatic Identity Matching
    custom identity mapping
    Custom Principal template
    Okta SSO last login enrichment
    Source Identity Assignments
    HRIS template

    OAA .NET SDK

    Building blocks for your custom OAA integration

    You can download the Veza C# SDK from .

    The Veza package provides data models, methods, and helpers for using the Open Authorization API. It provides helper methods to populate OAA templates for custom applications, filesystems, HRIS systems, and identity providers, and push the payloads to Veza. The SDK can also be used as a generic Veza API client.

    The Veza SDK includes the following core components:

    • Veza.Sdk.Client: A base API client for making REST calls to a Veza tenant

    • Veza.OAA.Client: An OAA API client for interacting with integration providers, data sources, and pushing OAA metadata to a Veza tenant.

    For example usage, see .

    Sample Workflow

    Create the Veza API connection and a new custom application:

    Once the CustomApplication class is instantiated, you can use its public methods to populate the new app with users, groups, resources, and permissions metadata:

    Once all identities, permissions, and resources are added to the CustomApplication object, use the client connection to push the data to Veza:

    See the directory for full examples.

    The Veza.OAA namespace provides exception types for common errors that occur when interacting with Veza APIs.

    • An OAAClientException is raised if there are errors interacting with the Veza API.

    • A TemplateException is raised if a provided payload does not conform to the template requirements. The inner exception will contain details about the exact issues encountered.

    Each OAA connector will be slightly different, depending on the methods each source application or service provides for retrieving entities, authorization, and other required metadata. You should consult the API documentation for your application when considering how you will source the information, and refer to existing Veza-supported OAA connectors for real-world examples.

    • OAA connector source code and Veza components are thoroughly annotated for reference when building your own integrations.

    • For additional information about developing a custom OAA integration, please see section of the User Guide.

    Handling Errors

    Additional Documentation

    oaa-app-outline.md
    quickstarts
    Open Authorization API
    GitHub
    using Veza.OAA;
    using Veza.OAA.Application;
    using Veza.OAA.Base;
    
    // inside namespace/class
                OAAClient oaaClient = new(api_key: <your_api_key>, url: <veza_tenant_url>);
                CustomApplication customApp = new(name: "sample app",
                    applicationType: "sample", description: "This is a sample application");
                // add custom permissions
                customApp.AddCustomPermission(name: "Admin", permissions: new List<Permission>
                    {
                        Permission.DataRead,
                        Permission.DataWrite,
                        Permission.MetadataRead,
                        Permission.MetadataWrite,
                        Permission.NonData
                    },
                    applyToSubResources: true
                );
    
                // define custom user properties
                customApp.DefinedProperties[typeof(User)].DefineProperty("is_guest", typeof(bool));
    
                // add user
                User user = customApp.AddUser(name: "bob");
                user.AddIdentity("bob@example.com");
                user.IsActive = true;
                user.CreatedAt = "2001-01-01T00:00:00.000Z".FromRFC3339();
                user.DeactivatedAt = "2003-03-01T00:00:00.000Z".FromRFC3339();
                user.LastLoginAt = "2002-02-01T00:00:00.000Z".FromRFC3339();
                user.PasswordLastChangedAt = "2004-04-01T00:00:00.000Z".FromRFC3339();
                user.SetProperty(name: "is_guest", value: false);
    
                // define group properties
                customApp.DefinedProperties[typeof(Group)].DefineProperty("group_id", typeof(int));
    
                // add group
                Group group1 = customApp.AddGroup("group1");
                group1.CreatedAt = "2001-01-01T00:00:00.000Z".FromRFC3339();
                group1.SetProperty(name: "group_id", 1);
                customApp.Users["bob"].AddGroup("group1");
                Group group2 = customApp.AddGroup("group2");
                group2.AddGroup("group1");
    
                // idp identities
                customApp.AddIdPIdentity("user01@example.com");
    
                // define role properties
                customApp.DefinedProperties[typeof(Role)].DefineProperty("custom", typeof(bool));
    
                // add roles
                Role role1 = customApp.AddRole(name: "role1", permissions: new List<string> { "all", "Admin", "Manage_Thing" });
                role1.SetProperty(name: "custom", value: false);
    
                // define resource properties
                customApp.DefineResourceProperty("private", typeof(bool), "thing");
    
                // add resources
                Resource thing1 = customApp.AddResource(name: "thing1", resourceType: "thing", description: "thing1");
                thing1.SetProperty(name: "private", false);
                thing1.AddTag(name: "tag1", value: "This is a value @,-_.");
                Resource cog1 = thing1.AddSubResource(name: "cog1", resourceType: "cog");
                cog1.AddConnection(id: "service_account@some-project.iam.gserviceaccount.com", nodeType: "GoogleCloudServiceAccount");
    
                // authorizations
                customApp.Users["bob"].AddRole(name: "role1", applyToApplication: true);
                customApp.Groups["group2"].AddRole(name: "role1", resources: new List<Resource> { thing1 });
                customApp.IdPIdentities["user01@example.com"].AddRole(name: "role1", applyToApplication: true);
    
                return customApp;
        await oaaClient.CreateProvider(provider_name: "sample app", custom_template: "application");
        await oaaClient.PushApplication(provider_name: "sample app", data_source_name: "sample app 1", customApp);

    Open Authorization API

    Using Veza APIs to add custom data and identity providers to the Veza Entity Catalog

    The Open Authorization API (OAA) is used to publish information about identities, authorization, and resources to the Veza Access Graph, making custom-built or otherwise-unsupported applications available for search, workflows, and monitoring. A typical motivation for using OAA is the need to integrate with enterprise applications that don't have an official Veza integration, such as a custom identity broker or source control management system.

    Each built-in Veza has a fixed schema unique to the provider. Integrations created with OAA can use either the Custom Identity Provider or Custom Application schema, both of which are flexible enough to model a wide range of data and identity sources.

    Several community connectors built on OAA are already available for immediate use, enabling easy connection to SaaS providers such as GitHub, Salesforce, and others. You can also develop a custom connector using the Veza-provided Python SDK oaaclient or your language of choice.

    To integrate a custom application using OAA, you will typically rely on an API (or another method) to list identities and resources within the host system, and retrieve entity and authorization metadata such as permissions, roles, and activity status. You must then structure this information according to one of the supported OAA templates. Once you have assembled the JSON payload, you can publish it using REST API calls or the oaaclient CLI.

    Use Cases

    Customers have utilized the Open Authorization API to accommodate many different scenarios. A few use cases include:

    • Using the GitHub connector to ensure that repositories holding critical source code are correctly configured.

    • Collecting infrastructure-as-a-code (IaC) configurations to audit which users can log in to important hosts.

    • Auditing the permissions granted by an internal developer portal.

    • Automating Lifecycle Management and Access Requests for custom applications that expose SCIM endpoints, enabling provisioning workflows for home-grown systems (see ).

    introduces important OAA workflows, the custom application template, and common API operations. When planning your connector, you may also want to review the for more information about naming considerations, mapping custom applications to the OAA schema, and other topics.

    Veza provides a and , which you can download using GitHub or pip install oaaclient. Examples and documentation are included with the source code.

    Alternatively, you can parse a data source, compile the JSON payload, and publish it using your language of choice. For detailed documentation on the OAA schema and API operations, see:

    • - suitable for most applications

    • - for custom Identity Providers

    • - operations for creating, updating, and deleting OAA providers and data sources

    First Steps

    Custom Application with SCIM
    Getting Started
    Best Practices
    Python SDK
    working example connectors
    Custom Application Template
    Custom Identity Provider Template
    API reference
    integration

    Utils

    oaaclient utility functions.

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    helper functions commonly used by OAA integrations


    function log_arg_error

    log_arg_error(log: object, arg: str = None, env: str = None) → None

    Helper function for logging errors when loading parameters

    Helper function used to create consistent messages in connectors when required parameters can be set at command line or as environment variables.

    Message can include information on parameter and/or environment variable but must provide one.

    Args:

    • log (object): logging facility object to log to

    • arg (str, optional): Command line option for parameter such as --veza-url. Defaults to None.

    • env (str, optional): OS Environment variable for parameter such as VEZA_URL. Defaults to None.

    Raises:

    • Exception: if neither arg or env are supplied


    Load JSON from file

    Args:

    • json_path (str): path to JSON file on disk

    Raises:

    • Exception: Unable to process JSON

    • Exception: Error reading JSON file

    Returns:

    • dict: JSON decoded to dictionary


    read an icon file to a base64 encoded string

    Args:

    • icon_path (str): Path to icon file on disk

    Returns:

    • str: base64 encoding of file



    Creates or updates a Veza report from a dictionary

    Creates a report and containing queries from a dictionary definition. Function will create any queries it does not find based on name. If a query with the same name already exists the existing query will be added to the report.

    If a report already exists with the same name any missing queries will be added to the report.

    report_definition must be a dictionary with name for the report and queries list of Veza query definitions:

    {"name": "My Report", "queries": [{..},{...}]}

    Args:

    • veza_con (OAAClient): OAAClient connection to make Veza API calls

    • report_definition (dict): Report definition

    Raises:

    • ValueError: Missing name or queries key

    Returns:

    • dict: API response from Report creation or update


    Helper function to truncate strings

    Helper function to truncate strings to conform to maximum length requirements for templates.

    Returns a string that is the first N bytes of the source string

    Args:

    • source_str (str): Source string to truncate

    • length (int, optional): Length to shorten to. Defaults to 256.

    Returns:

    • str: truncated string

    OAA Templates

    JSON schemas for describing custom applications, identity providers, principals, file systems, and other authorization sources

    OAA utilizes templates (JSON schema) for structuring authorization and identity metadata, combined with a REST API to register, update and manage the data. Once uploaded, Veza processes the template payload and incorporates the entities and permissions into the Authorization Metadata Graph.

    Choosing the appropriate template is the first step in creating a new integration with OAA. The template provides a schema for describing the identities, resources, and authorization relationships local to the OAA data source.

    For most applications, SaaS Apps and systems the provides a generic and flexible model to capture authorization data for users and groups to the system and its resources.

    A custom application is structured with the following main entities:

    • Application

    Resource

    • Sub-resource

      • Sub-resource

        • Additional sub-resources

  • Local Users

  • Local Groups

  • Local Roles

  • Local Permissions

  • Identity-to-permissions binding

  • Intended for modeling sources of users, group, and federated identity metadata, the Custom Identity Provider Template can be used to enumerate users and groups that access other external applications and resources, similar to built-in connectors for Okta and AzureAD. These users and groups typically represent the top-level corporate identities within an organization.

    A Custom Identity Provider can have the following entities:

    • Domains

    • Users

    • Groups

    The Custom IdP template also includes the option to define AWS Roles that are assumable by users and groups and can work with Access Review Workflows to auto-assign resource managers.

    For modeling sources of identities (users, groups, and tenants) that connect to other OAA data sources on the same provider, the Custom Principal Template provides a lightweight identity model. Unlike the Custom IdP, which models a full identity provider with domains, the Principal template is designed to feed users and groups into Custom Application or other templates on the same provider.

    A Custom Principal is structured with:

    • Tenant

    • Users

    • Groups

    For publishing employee metadata from an HR platform, the HRIS Template captures employment status, reporting lines, and organizational units. Unlike an identity provider, an HRIS does not usually grant access to other systems, so this template feeds Lifecycle Management events, identity correlation, and Access Review enrichment rather than authorization paths.

    An HRIS submission is structured with:

    • System

      • Employees

      • Groups

    For modeling secret and credential management systems, the Secret Store Template captures vaults, entries, permissions, and identity access mappings. Use this template to connect custom or self-hosted credential management systems that are not covered by a native Veza integration.

    A Secret Store is structured with:

    • Secret Store

      • Permissions

      • Vaults

        • Entries

          • Identities

    • Identity-to-Permission Bindings

    The Entity Enrichment Template adds custom property values to entities that already exist in the Veza authorization graph from other integrations. Use this template to attach supplemental metadata (such as compliance status, cost center, or internal identifiers) to entities discovered by native integrations.

    An Entity Enrichment submission contains:

    • Enriched entity property definitions (schema declarations)

    • Enriched entities (entity references with property values)

    For modeling file servers and file storage platforms, the File System Template captures which identities hold which permissions on servers, shares, and directories. Use it for storage systems that are not covered by a native Veza integration.

    A File System has two submission modes, one for a server and its mounts and one for the folders within a mount:

    • Server

      • Mounts

        • Folders

    • Permissions

    • Identity-to-permission bindings

    For bringing asset inventory into Veza, the CMDB Template captures configuration items from a configuration management database and correlates each one to the identity that owns it and to the Veza entity it describes.

    A CMDB submission is structured with:

    • CMDB instance

      • Configuration items

    • Owner and asset correlation configuration

    For submitting findings from an external secret scanning tool, the Secret Scanner Template records where credentials were found in source control so they can be correlated with matching credentials in Azure Key Vault. Unlike the other templates, a submission is a single flat list of findings with no entity hierarchy.

    For modeling access to host machines such as Linux and Windows servers, the Host Template captures the accounts, groups, and credentials on each host. It also captures the privileges that principals hold on the host and on services or commands inside it. Grants can name identity provider users and groups directly, so directory principals allowed to sign in need no local definition.

    A Host submission is structured with:

    • Environment

    • Hosts

      • Users

      • Groups

      • Credentials

      • Resources

      • Identity-to-privilege grants

    • Privilege definitions

    Custom Application

    Custom Application Template

    Custom Identity Provider

    Custom Principal

    Custom HRIS Provider

    Secret Store

    Entity Enrichment

    File System

    CMDB

    Secret Scanner

    Host

    function load_json_from_file

    function encode_icon_file

    function exists_in_query_array

    function build_report

    function truncate_string

    load_json_from_file(json_path: str) → dict
    encode_icon_file(icon_path: str) → str
    exists_in_query_array(value_to_find, input_array) → bool
    build_report(veza_con, report_definition: dict) → dict
    truncate_string(source_str: str, length: int = 256) → str

    Exceptions

    Exception raised for OAA template schema violations.

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.


    class OAATemplateException

    General exception used for violations of the template schema.

    method __init__

    __init__(message)

    Multipart Upload

    Upload large OAA payloads using chunked multipart requests

    Overview

    For OAA payloads that exceed 100 MB after compression, you can use multipart upload to split the payload into smaller chunks and upload them sequentially. The Veza platform assembles the chunks server-side before processing.

    Multipart upload is useful when:

    • The payload is too large for a single HTTP request

    • Network reliability is a concern for large transfers

    • You need to monitor upload progress for very large data sources

    The standard :push endpoint supports payloads up to 100 MB (compressed or uncompressed). Use multipart upload when your payload approaches or exceeds this limit, or when you need more reliable transfer for large payloads.

    How it works

    1. Start the upload by sending a start request — the server creates an upload session and returns an upload_id.

    2. Upload chunks sequentially, each base64-encoding a raw slice of the payload. Include the upload_id from step 1 and an incrementing sequence_number.

    3. Finalize by sending a complete request with the upload_id and total sequence_count.

    Each chunk must be base64-encoded from raw bytes before sending. The server decodes and reassembles chunks in sequence order when the complete operation is received.

    Field
    Type
    Description

    The response returns an upload_id (UUID string) to use in all subsequent requests for this upload session.

    Field
    Type
    Description

    Send a separate POST to the same endpoint after all chunks are uploaded:

    Field
    Type
    Description

    The oaaclient Python SDK handles multipart upload automatically when enabled:

    When enable_multipart is set to True, the SDK automatically switches to multipart for payloads exceeding 50 MB (uncompressed) and:

    • Splits the payload into chunks and base64-encodes each one individually

    • Starts an upload session and tracks the upload_id

    • Uploads each chunk sequentially with the correct sequence_number

    • Sends the completion operation to trigger server-side assembly

    • All chunks for a given upload_id must be uploaded before sending the completion operation.

    • You can re-upload a chunk with the same sequence_number and upload_id if needed — the last upload for a given sequence number is used. All chunks must be present before the completion operation is sent.

    • Chunk order is determined by sequence_number, not upload order.

    oaaclient modules

    Modules

    • oaaclient.templates: Classes for constructing an OAA JSON payload, one page per supported template.

    • client: Classes for calling Veza APIs and managing OAA providers and data sources.

    • structures: Data structures supporting the OAA templates.

    • : oaaclient utility functions.

    • : Class for OAA API Connection and Management.

    • : Error raised by OAAClient.

    • : Error with API Connection

    • : Error returned from API Call

    • : Entry point for oaaclient-report-builder command

    • : Creates or updates a Veza report from a dictionary

    • : read an icon file to a base64 encoded string

    Enrichment

    Classes for constructing an OAA JSON payload for Entity Enrichment

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • PROPERTY_NAME_REGEX


    Class for modeling Entity Enrichment using the OAA Entity Enrichment template.

    The Entity Enrichment template attaches custom properties to existing Veza entities (such as AwsIamRole, AwsIamUser or OktaUser

    client.OAARetry: Super class for urllib3.util.retry

  • structures.CaseInsensitiveDict: Case Insensitive Key Dictionary

  • utils.exists_in_query_array

  • utils.load_json_from_file: Load JSON from file

  • utils.log_arg_error: Helper function for logging errors when loading parameters

  • utils.truncate_string: Helper function to truncate strings

  • Classes

    Functions

    utils
    client.OAAClient
    client.OAAClientError
    client.OAAConnectionError
    client.OAAResponseError
    client.main
    client.report_builder_entrypoint
    utils.build_report
    utils.encode_icon_file

    string

    Base64-encoded chunk of the raw payload

    operation

    string

    Must be start

    operation

    string

    Must be upload

    upload_id

    string

    UUID returned by the start response

    sequence_number

    integer

    Sequence number for this chunk, starting from 1. Maximum 99 chunks per upload.

    operation

    string

    Must be complete

    upload_id

    string

    UUID from the start response

    sequence_count

    integer

    Total number of chunks uploaded

    API endpoint

    Start request body

    Chunk request body

    Finalization request body

    Example

    Using the Python SDK

    Notes

    data

    ) discovered by other integrations. Unlike other OAA templates it does not create new entities; it only enriches existing ones with additional searchable metadata.

    Enriched entities are tracked internally in a case insensitive dictionary keyed by the composite of entity type, data source id, and id so the same entity id can be enriched across multiple data sources or types. The index is private; use add_entity to add entities and get_entity to retrieve them.

    Args:

    • name (str): Name for the Entity Enrichment instance. Used when creating the provider but not included in the payload itself.

    Attributes:

    • name (str): Name for the Entity Enrichment instance

    • property_definitions (EntityEnrichmentPropertyDefinitions): Custom property definitions grouped by Veza entity type


    Add an entity to enrich

    Creates a new EnrichedEntity for an existing Veza entity. The entity is tracked internally keyed by the composite of entity type, data source id, and id so each entity may appear only once within the payload.

    Args:

    • entity_type (str): Veza entity type (e.g. "AwsIamRole", "OktaUser")

    • id (str): Veza unique ID for the entity. For AWS entities this is the ARN.

    • data_source_id (str): ID of the Veza data source that owns the entity. For AWS this is the account

    • ID combined with the data source type (e.g. "339083562601: awsiam").

    Raises:

    • OAATemplateException: Entity with the same type, id, and data_source_id already exists

    Returns:

    • EnrichedEntity: Entity for the new enrichment record


    Get a previously added entity to enrich.

    Looks up an entity added with add_entity by its type, id, and data source id.

    Args:

    • entity_type (str): Veza entity type (e.g. "AwsIamRole", "OktaUser")

    • id (str): Veza unique ID for the entity. For AWS entities this is the ARN.

    • data_source_id (str): ID of the Veza data source that owns the entity.

    Raises:

    • OAATemplateException: No entity with the given type, id, and data_source_id has been added

    Returns:

    • EnrichedEntity: The matching enrichment record


    Get the OAA payload.

    Returns the complete OAA template payload for entity enrichment as serializable dictionary

    Returns:

    • dict: OAA payload as dictionary


    Enriched Entity

    Represents a single Veza entity to enrich with custom property values. The entity is identified by the combination of entity_type, id and data_source_id. Init variables are all required and must not be empty such as "".

    Args:

    • entity_type (str): Veza entity type, e.g. "AwsIamRole", "OktaUser"

    • id (str): Veza unique ID for the entity. For AWS entities this is the ARN.

    • data_source_id (str): ID of the Veza data source that owns the entity.

    Raises:

    • ValueError: Any of the required arguments are empty.


    Set Enriched Entity custom property value

    Property name must be defined for the entity's type before calling set_property

    Args:

    • property_name (str): Name of property

    • property_value (any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined for the entity type.


    Output enriched entity to dictionary for payload.


    Model for defining custom properties for Entity Enrichment.

    Property definitions are grouped by Veza entity type. Each entity type maintains its own set of property names and types that may be set on enriched entities of that type.

    Attributes:

    • entity_properties (dict): Property definitions keyed by entity type. Each value is a dictionary mapping property name to its OAAPropertyType.


    Define a property for an entity type.

    Args:

    • entity_type (str): Veza entity type the property applies to (e.g. "AwsIamRole")

    • name (str): name for property

    • property_type (OAAPropertyType): type for property

    Raises:

    • OAATemplateException: entity_type is not a non-empty string

    • OAATemplateException: name contains invalid characters or is not a string

    • OAATemplateException: property_type is not an OAAPropertyType enum


    Return property definitions as list ready for OAA payload


    Check property name for valid characters

    Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.

    Args:

    • name (str): name of property to validate

    Raises:

    • OAATemplateException: Name is not a string

    • OAATemplateException: Name contains invalid characters or does not start with a letter

    class EntityEnrichment

    method __init__

    method add_entity

    method get_entity

    method get_payload

    class EnrichedEntity

    method __init__

    method set_property

    method to_dict

    class EntityEnrichmentPropertyDefinitions

    method __init__

    method define_property

    method to_dict

    method validate_name

    POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:parts
    PAYLOAD_FILE="large_payload.json"
    CHUNK_SIZE=10485760  # 10 MB per chunk
    
    # 1. Start the upload session
    RESPONSE=$(curl -s -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:parts" \
      -H "authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"operation":"start"}')
    UPLOAD_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['upload_id'])")
    
    # 2. Split into raw chunks and upload each
    SEQUENCE=0
    split -b $CHUNK_SIZE "$PAYLOAD_FILE" /tmp/oaa_chunk_
    for CHUNK_FILE in $(ls /tmp/oaa_chunk_* | sort); do
      SEQUENCE=$((SEQUENCE + 1))
      ENCODED=$(base64 -w 0 < "$CHUNK_FILE")  # use -b 0 on macOS
    
      curl -s -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:parts" \
        -H "authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -d "{
          \"operation\": \"upload\",
          \"upload_id\": \"$UPLOAD_ID\",
          \"sequence_number\": $SEQUENCE,
          \"data\": \"$ENCODED\"
        }"
    done
    
    # 3. Finalize the upload
    curl -s -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:parts" \
      -H "authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d "{
        \"operation\": \"complete\",
        \"upload_id\": \"$UPLOAD_ID\",
        \"sequence_count\": $SEQUENCE
      }"
    
    rm /tmp/oaa_chunk_*
    from oaaclient.client import OAAClient
    
    client = OAAClient(url=veza_url, token=veza_api_key)
    client.enable_multipart = True
    
    # Push as usual - the SDK automatically chunks large payloads
    client.push_application(provider_name, data_source_name, application_object=app)
    __init__(name: 'str')
    add_entity(
        entity_type: 'str',
        id: 'str',
        data_source_id: 'str'
    ) → EnrichedEntity
    get_entity(
        entity_type: 'str',
        id: 'str',
        data_source_id: 'str'
    ) → EnrichedEntity
    get_payload() → dict
    __init__(entity_type: 'str', id: 'str', data_source_id: 'str')
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__()
    define_property(
        entity_type: 'str',
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    to_dict() → list
    validate_name(name: 'str') → None

    HRIS

    Classes for constructing an OAA JSON payload for custom HRIS

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • PROPERTY_NAME_REGEX


    Class for modeling Human Resource Information Systems (HRIS) Template

    HRIS template consists of base information about the HRIS instance, Employees and Groups.

    Employees and Groups are tracked in case insensitive dictionaries that can be used to reference entities after creation.

    Args:

    name (str): Name for HRIS Instance

  • hris_type (str): Type for HRIS. Typically the vendor or product name.

  • url (str): Instance URL for HRIS.

  • Attributes:

    • employees (dict[string]): Dictionary of HRISEmployee instances keyed by Employee ID

    • groups (dict[string]): Dictionary of HRISGroup instances keyed by Group ID


    Add a new Employee

    Function creates a new HRISEmployee instance and adds it to the HRISProvider.employees keyed by the unique_id

    Args:

    • unique_id (str): Unique Identifier for Employee

    • name (str): Display name for employee

    • employee_number (str): The employee's number that appears in the third-party integration.

    • first_name (str): Employee first name

    • last_name (str): Employee last name (family name)

    • is_active (bool): Boolean for employee active status

    • employment_status (str): String representation of employee status, e.g. "ACTIVE", "TERMINATE", "PENDING"

    Raises:

    • OAATemplateException: Employee with ID already exists

    Returns:

    • HRISEmployee: Entity for new employee


    Add a new Group

    Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups. Groups can also be members of other groups to create hierarchy.

    Some properties of HRISEmployee such as department must reference an existing HRISGroup by its ID.

    Args:

    • unique_id (str): Unique ID for group

    • name (str): Display name

    • group_type (str): Type for group such as "Team", "Department", "Cost Center"

    Returns:

    • HRISGroup: Entity for new group


    Get the OAA payload.

    Returns the complete OAA template payload for HRIS as serializable dictionary

    Returns:

    • dict: OAA payload as dictionary


    HRISSystem information

    Representation for HRISSystem information. The system information is used to represent additional details for the HRIS Instance.

    Args:

    • name (str): Name for system Instance

    • url (str, optional): URL for instance . Defaults to "". TODO: Is this right?

    Attributes:

    • identity_mapping_configuration (IdentityMappingConfigurationSubmission): Identity mapping configuration, set via set_identity_mapping_configuration().


    Link HRIS to External IdP of given type

    Sets the IdP types (Okta, AzureAD, etc.) for Veza to link employee identities to.

    Args:

    • provider_type (IdPProviderType): Type of IdP for source identities

    Raises:

    • ValueError: provider_type must be IdPProviderType enum

    Returns:

    • list[IdPProviderType]: List of configured IdP types


    Create and set the identity mapping configuration.

    Initializes the identity_mapping_configuration attribute with a new IdentityMappingConfigurationSubmission instance and returns it for further configuration.

    Returns:

    • IdentityMappingConfigurationSubmission: The identity mapping configuration.



    HRIS Employee Entity

    Represents an employee record in the HRIS system. Each employee must have a unique ID to identify it in the payload. This ID is also used to reference one employee to the other for manager hierarchy.

    Init variables are all required and must not be empty such as ""

    Args:

    • unique_id (str): Unique Identifier for Employee

    • name (str): Name for employee record.

    • employee_number (str): The employee's number that appears in the third-party integration.

    • first_name (str): Employee first name

    • last_name (str): Employee last name (family name)

    • is_active (bool): Boolean for employee active status

    • employment_status (str): String representation of employee status, e.g. "ACTIVE", "TERMINATE", "PENDING"

    Parameters:

    • company (str): The company (or subsidiary) the employee works for.

    • preferred_name (str): The employee's preferred first name.

    • display_full_name (str): The employee's full name, to use for display purposes.

    • canonical_name (str): The employee's canonical name.

    • username (str): The employee's username that appears in the integration UI.

    • email (str): The employee's work email.

    • idpid (str): The ID for this employee on the destination IDP provider used to automatically connect to it, if not supplied email is used.

    • personal_email (str): The employee's personal email.

    • home_location (str): The employee's home location.

    • work_location (str): The employee's work location.

    • cost_center (str): The cost center ID (Group ID) that the employee is in.

    • department (str): The department ID (Group ID) that the employee is in.

    • managers (str): The employee IDs of the employee's managers.

    • groups (str): The IDs of groups this user is in

    • start_date (str): The date that the employee started working. RFC3339 timestamp.

    • termination_date (str): The employee's termination date. RFC3339 timestamp.

    • job_title (str): The title of the employee.

    • employment_typ (str): The employee's type of employment. For example: FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE.

    • primary_time_zone (str): The time zone which the employee primarily lives.

    Raises:

    • ValueError: Any of the required arguments are empty.


    Add employee to group

    Adds employee to a group by the group ID. Group must also be defined for HRISInstance with HRISProvider.add_group()

    Args:

    • group_id (str): Unique ID of HRISGroup to add employee too


    Add manager to Employee

    Adds a manager to the employee by the manager's HRISEmployee instance unique ID. Manger employee record must also exist.

    Args:

    • manager_id (str): Unique ID for manager HRISEmployee instance


    Set Employee custom property value

    Property name must be defined for employee before calling set_property

    Args:

    • property_name (str): Name of property

    • property_value (any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Output employee to dictionary for payload.


    HRIS Group

    Represents any group of employees in the HRIS system. HRISGroups can be used to represent teams, departments, cost centers or any organizational unit. Each group has a type to make searching and grouping easier.

    Group's Unique ID must be unique across all group types.

    Args:

    • unique_id (str): Unique ID for group

    • name (str): Display name

    • group_type (str): Type for group such as "Team", "Department", "Cost Center"


    Set HRIS Group custom property value

    Property name must be defined for group before calling set_property

    Args:

    • property_name (str): Name of property

    • property_value (any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Dictionary output for inclusion in payload







    Check property name for valid characters

    Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.

    Args:

    • name (str): name of property to validate

    Raises:

    • OAATemplateException: Name is not a string

    • OAATemplateException: Name contains invalid characters or does not start with a letter

    class HRISProvider

    method __init__

    method add_employee

    method add_group

    method get_payload

    class HRISSystem

    method __init__

    method add_idp_type

    method set_identity_mapping_configuration

    method to_dict

    class HRISEmployee

    method __init__

    method add_group

    method add_manager

    method set_property

    method to_dict

    class HRISGroup

    method __init__

    method set_property

    method to_dict

    class HRISPropertyDefinitions

    method __init__

    method define_employee_property

    method define_group_property

    method define_system_property

    method to_dict

    method validate_name

    __init__(name: 'str', hris_type: 'str', url: 'str')
    add_employee(
        unique_id: 'str',
        name: 'str',
        employee_number: 'str',
        first_name: 'str',
        last_name: 'str',
        is_active: 'bool',
        employment_status: 'str'
    ) → HRISEmployee
    add_group(unique_id: 'str', name: 'str', group_type: 'str') → HRISGroup
    get_payload() → dict
    __init__(name: 'str', url: 'str' = '')
    add_idp_type(provider_type: 'IdPProviderType') → list[IdPProviderType]
    set_identity_mapping_configuration() → IdentityMappingConfigurationSubmission
    to_dict() → dict
    __init__(
        unique_id: 'str',
        name: 'str',
        employee_number: 'str',
        first_name: 'str',
        last_name: 'str',
        is_active: 'bool',
        employment_status: 'str'
    )
    add_group(group_id: 'str') → None
    add_manager(manager_id: 'str') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(unique_id: 'str', name: 'str', group_type: 'str')
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__()
    define_employee_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_group_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_system_property(name: 'str', property_type: 'OAAPropertyType') → None
    to_dict() → dict
    validate_name(name: 'str') → None

    Getting Started

    Overview and first steps for building an Open Authorization API connector

    A built-in Veza integration or OAA connector might not be available for an application or identity provider you want to connect to Veza. However, you can still use the Open Authorization API to integrate compatible applications and identity providers with the rest of your Veza data catalog.

    The adaptable OAA schema can model a wide range of authorization models and resource hierarchies, and you will typically have several options for sourcing authorization metadata from the application provider. To integrate a custom application with Veza, you will need to be able to:

    1. Extract metadata from the source application using an API, command line, or another method to collect the needed authorization-related data. Depending on the application, this could include data resources and sub-resources as well as local users, groups, roles, permissions, and correlation to federated identities or external IDs.

    2. Generate a payload describing the users, resources, and permissions, according to a standard JSON schema. The payload can describe any number of application resources and sub-resources, along with information about identities, groups, permissions, and relationships to other graph entities.

    3. for processing using Veza APIs (after registering a new custom provider and data source if they don't already exist).

    The process of retrieving user records, along with lists of resources, group and permissions information, will be unique to each technology and OAA connector. You may also need to consider how to adapt the application's implementation of roles, federated identities, and resource hierarchies to fit the .

    Before building a connector, you should read the best practices for and , or see the current list of for real-world examples.

    Most programming languages offer ways to populate and manipulate a JSON schema. You can also use the for prebuilt functions:

    Below is an example of a populated application template. It demonstrates the basic principles of modeling local user permissions on application resources. For more details on all the available entities and properties see the full reference:

    In addition to built-in properties such as department or last_login_at, most entities can have additional user-defined custom properties. Using enables integrations to capture application-specific data that can be useful for reporting and provide additional insight during investigations.

    You can also apply to entities within the payload.

    You will use the Veza REST API to create, delete, and update a custom data source under v1/providers/custom/{provider_id}/{datasource_id}. Before you can push an OAA payload, you will need to:

    • Add a custom Provider to represent the generic application provider (such as "GitHub"), and set the name and template (application or IdP).

    • Bind a custom Data Source to the new custom Provider (such as "GitHub Organization") to activate it in the data pipeline. The data source will be the destination for future pushes and updates, and should usually represent the top-level instance of the modeled application.

    • Push the payload to populate the Veza Access Graph with new entities and metadata for the custom data source.

    Identity Providers and HR Information Systems can be used as identity sources in Provisioning Policies by marking the Provider as a provisioning source. Identities from these sources will be available when configuring Provisioning Policies.

    Applications integrated via OAA can be managed through LCM Workflows via one of two methods:

    • SCIM - If the application supports SCIM provisioning, you can configure Veza to manage application access directly through SCIM. See for more information.

    • REST - For applications that support REST API calls to manage access, actions can be created in LCM Workflows to manage access.

    To update the data, push a new payload to the original provider ID and data source ID. By default, Veza will overwrite any existing data. The previous state will be available in the graph history, based on Veza's snapshot retention schedule.

    Optionally, subsequent changes can be , where the payload only contains entities to modify, add, or remove.

    The module can be used to instantiate a Veza connection and manage OAA providers:

    See for additional documentation.

    Alternatively, you can make the required REST API calls using the client of your choice or by invoking oaaclient as a .

    • Typically, the provider should represent the provider name (such as "CustomSCM"). Any payload pushes will target the data source ("CustomSCMInstance") under the custom provider. The pushed payload can include many nested resources (such as multiple repositories). The template also supports resources with a variety of different types within a single application.

    • The data source and provider name are primarily for internal use. The application_type specified in the template is used when viewing and searching the custom app from the Veza UI.

    Veza enforces strict validation of the json_data field containing the OAA payload. Three checks are performed:

    1. All required fields must be present.

    2. String fields must be valid UTF-8 strings, no larger than 512 characters for names and IDs, and 4,096 for all other string values.

    3. The maximum single payload size is 100MB. If you need to compress the payload, you can enable the option when . You can use multi-part upload for large payloads.

    A successful response may include warnings for issues that didn't prevent the processing of OAA data but should still be investigated. When mapping identities to an , a warning will be raised if a matching IdP group name or user principal name can't be found.

    • To validate an Azure AD or other type of user, go to the Access Graph, search for the node of interest, select Show Details, and confirm the principal name is correct.

    • To validate the identifier for a group, find the node for the group and verify the name is as expected.

    Veza will always return the warnings key in the response. If a response is empty, there are no warnings.

    For all Veza APIs, include an error code (in standard gRPC error, such as 3 for Invalid Argument) and a descriptive error message. The error message consists of two parts:

    1. The field in which the error occurs

    2. The detailed reason for the error

    Example Connectors

    Open Authorization API usage examples

    The official Veza connectors are useful references for understanding the decisions and strategies that come into play when building a custom Open Authorization API (OAA) integration.

    Each connector is similar in basic function, yet adapts to the resource hierarchies and interfaces unique to the technology provider. Each uses the oaaclient Python package to construct a payload, create a custom provider and data source, and publish the extracted metadata.

    Veza provides working connectors and source code for:

    • GitHub

    • GitLab

    • Jira

    • Looker

    • PagerDuty

    • Zendesk

    See the for setup instructions and the most recent releases. The repository also includes sample applications demonstrating basic oaaclient usage. You can also browse these examples in the .

    GitHub repository
    User Guide

    You can use the Python SDK to simplify the process of populating the payload, connecting to Veza, and managing OAA providers and data sources.

    1. Extracting metadata from the source application

    Typically, the required information will be available from an API, but you should consult the provider's documentation to ensure the information is available, and consider an alternative method for sourcing the data, if not.

    2. Generating a sample payload

    Custom Application Payload

    Custom Properties

    3. Creating and Updating Custom Providers and Data Sources

    Enabling for Life Cycle Management (optional)

    Identity Providers and HR Information Systems

    Applications

    Updates

    You can use GET to retrieve any existing provider and data source IDs. For more information about managing Providers and Data Sources see REST API Operations.

    Using oaaclient

    Notes

    Troubleshooting

    Warnings

    Errors

    Publish the payload
    OAA template
    sourcing metadata
    naming conventions
    community connectors on GitHub
    Python SDK
    Custom Application
    custom properties
    Veza tags
    Custom Application with SCIM (OAA)
    Send REST Payload
    incremental updates
    oaaclient.client
    Client
    command-line tool
    creating the OAA data source
    external id
    error messages
    custom_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
    jane = custom_app.add_local_user("jane", identities="jane@example.com")
    resource1 = custom_app.add_resource(name="customers", resource_type="database")
    jane.add_permission(permission="owner", resources=[customers])
    from oaaclient.client import OAAClient
    from oaaclient.templates import CustomApplication, OAAPermission
    
    # creates a connection class to communicate with Veza
    veza_con = OAAClient(url=veza_url, token=veza_api_key)
    
    # creates a new Custom Application model
    custom_app = CustomApplication(name="Sample App", application_type="sample")
    {
      "warnings": [
        {
          "message": "Cannot find identity by names (values: unknown_user@veza.com)"
        }
      ]
    }
    {
      "applications": [
        {
          "name": "Support Portal",
          "application_type": "support_portal",
          "description": "Our customer support portal",
          "local_users": [
            {
              "name": "bob",
              "identities": [
                "bob@example.com"
              ],
              "groups": [
                "admins"
              ],
              "is_active": true,
              "last_login_at": "2022-03-21T18:56:38Z"
            },
            {
              "name": "sue",
              "identities": [
                "sue@example.com"
              ]        }
          ],
          "local_groups": [
            {
              "name": "admins"
            }
          ]
        }
      ],
      "permissions": [
        {
          "name": "admin",
          "permission_type": [
            "DataWrite",
            "DataRead",
            "DataDelete",
            "MetadataWrite",
            "MetadataRead"
          ]
        },
        {
          "name": "login",
          "permission_type": [
            "DataRead",
            "MetadataRead"
          ]
        }
      ],
      "identity_to_permissions": [
        {
          "identity": "bob",
          "identity_type": "local_user",
          "application_permissions": [
            {
              "application": "Support Portal",
              "permission": "login"
    
            }
          ]
        },
        {
          "identity": "sue",
          "identity_type": "local_user",
          "application_permissions": [
            {
              "application": "Support Portal",
              "permission": "login"
    
            }
          ]
        },
        {
          "identity": "admins",
          "identity_type": "local_group",
          "application_permissions": [
            {
              "application": "Support Portal",
              "permission": "admin"
            }
          ]
        }
      ]
    }

    Templates

    Classes for constructing an OAA JSON payload, one page per supported template.

    Modules

    • application: Classes for constructing an OAA JSON payload for Custom Application

    • common: Shared base classes, enums and identity-mapping submission types used across the OAA templates.

    • enrichment: Classes for constructing an OAA JSON payload for Entity Enrichment

    • : Exception raised for OAA template schema violations.

    • : Classes for constructing an OAA JSON payload for the Host template

    • : Classes for constructing an OAA JSON payload for custom HRIS

    • : Classes for constructing an OAA JSON payload for Custom IDP

    • : Classes for constructing an OAA JSON payload for Custom Principal Submission

    • : Classes for constructing an OAA JSON payload for Secret Store

    • : Access Credential derived from Identity base class.

    • : Base class for CustomApplication.

    • : Model for defining custom properties for application and its entities (users, groups, roles, resources).

    • : Class for modeling application authorization using the OAA Application template.

    • : Veza supported IdP provider types.

    • : Identity mapping configuration submission.

    • : Identity mapping destination datasource.

    • : Enriched Entity

    • : Class for modeling Entity Enrichment using the OAA Entity Enrichment template.

    • : Model for defining custom properties for Entity Enrichment.

    • : General exception used for violations of the template schema.

    • : A credential that authenticates as an account on a Host.

    • : Environment for a Host fleet.

    • : Whether a HostGrant's principal is a user or a group.

    • : A group on a Host.

    • : HRIS Employee Entity

    • : HRIS Group

    • : Class for modeling Human Resource Information Systems (HRIS) Template

    • : App model for CustomIdPProvider

    • : Domain model for Custom IdP provider.

    • : Group model for CustomIdPProvider.

    • : CustomIdPProvider class for modeling Identity Providers (IdP) using OAA Custom Identity Provider Template.

    • : CustomPrincipal class for modeling Principal services using OAA Custom Principal Template.

    • : Group model for CustomPrincipal.

    • : Tenant model for Custom Principal submission.

    • : User model for CustomPrincipal

    • : Identity to Permission Mapping

    • : Permission Assignment

    • : Secret Store Entity

    • : Secret Store Permission Entity

    • : Helper function to simplify appending.

    • : Returns a list of unique strings from input list case insensitive

    Secret Scanner

    Template for submitting leaked secret findings from external secret scanning tools

    Use this template to bring findings from an external secret scanning tool into Veza using the . Each finding records one place a credential was found in source control, so that leaked credentials can be correlated with the matching secrets in Azure Key Vault.

    This template is smaller than the others. It has no application, resource, or identity entities, no permission model, and no custom properties. A submission is a single flat list of findings.

    Secret scanner
    Other templates

    Modeling Users, Permissions, and Roles

    Using local roles, local users, and canonical permissions to describe access

    Most applications will have some concept of a “local user” that can have varying permissions to data and metadata. Most modern cloud applications offer some form of single sign-on. In some cases, local user accounts correspond to an external federated identity, or even only exist ephemerally.

    The Open Authorization API is able to represent local users, local groups, and external identities. An external identity could be an user connecting directly to a resource through Single Sign On, or an SSO group. A local user could be a just-in-time account created when an IdP user first connects.

    You should represent system users using objects, even for apps that are SSO-enabled. The local user object is able to contain useful attributes such as activity status and timestamps, enabling rich search on those entities. A local user can also reference a federated identity, creating graph relationships between IdP entities and local users and groups when the payload is parsed. Veza handles these cross service connections similarly to built-in integrations such as Snowflake.

    • The OAA template supports direct permissions from IdP users to resources. However, including a local user entity in your OAA mapping strategy is still recommended when possible.

    application.CustomPermission: CustomPermission class for defining CustomApplication permissions.

  • application.CustomResource: Class for resources and sub-resources.

  • application.IdPIdentity: IdP identity derived from Identity base class.

  • application.Identity: Base class for deriving all identity types (should not be used directly).

  • application.LocalAgent: Local Agent identity, derived from Identity base class.

  • application.LocalGroup: LocalGroup identity.

  • application.LocalModel: Represents an AI model entity within an application.

  • application.LocalRole: Represent a Custom Application Local Role.

  • application.LocalUser: LocalUser identity, derived from Identity base class.

  • application.LocalUserType: Types of local user account, human or service account.

  • application.OAAIdentityType: Types of identities for permission mapping.

  • application.OAAPermission: Canonical permissions used by Veza Authorization Framework.

  • common.IdentityMappingMode: Identity mapping mode.
  • common.IdentityMappingProperty: Identity property used as source or destination in a property matcher.

  • common.IdentityMappingPropertyMatchersSubmission: Identity mapping property matcher.

  • common.IdentityMappingSubmission: Identity mapping submission.

  • common.IdentityMappingTransformation: Identity mapping transformation applied to identity values before matching.

  • common.IdentityMappingType: Identity mapping match type.

  • common.OAAOwnerType: Node types for entity owners

  • common.OAAPropertyType: Supported types for custom properties on OAA entities such as application, resource, and identity.

  • common.Provider: Base class for CustomProvider.

  • common.Tag: Veza Tag data model.

  • host.HostIdentityType: Whether a HostUser stands for a person or not.
  • host.HostNode: A single host machine.

  • host.HostPrivilegeDefinition: A privilege defined once on the fleet and referenced by name wherever it is granted.

  • host.HostPropertyDefinitions: Model for defining custom properties for a Host fleet's hosts, users, groups and resources.

  • host.HostProvider: Class for modeling host machine authorization using the OAA Host template.

  • host.HostResource: Something inside a host that a privilege can apply to.

  • host.HostUser: A user account on a Host.

  • hris.HRISSystem: HRISSystem information

    idp.CustomIdPUser: User model for CustomIdPProvider.

  • idp.IdPEntityType: IdP entity types.

  • idp.IdPPropertyDefinitions: Model for defining custom properties for CustomIdPProvider and its entities (users, groups, domain).

  • idp.IdPUserIdentityType: Types of identities for permission mapping.

  • principal.PrincipalEntityType: Principal entity types.

  • principal.PrincipalPropertyDefinitions: Model for defining custom properties for CustomPrincipal and its entities (tenant, users, groups).

  • secret_store.SecretStorePropertyDefinitions: Property Definitions for Secret Store entities
  • secret_store.SecretStoreSubmission: Class for modeling Secret Store Template

  • secret_store.SecretStoreVault: Secret Store Vault Entity

  • secret_store.SecretStoreVaultEntry: Secret Store Vault Entry Entity

  • secret_store.VaultEntryIdentity: Vault Entry Identity

  • Classes

    Application

    Common

    Enrichment

    Exceptions

    Host

    HRIS

    IdP

    Principal

    Secret Store

    Functions

    exceptions
    host
    hris
    idp
    principal
    secret_store
    application.AccessCred
    application.Application
    application.ApplicationPropertyDefinitions
    application.CustomApplication
    common.EntityOwner
    common.IdPProviderType
    common.IdentityMappingConfigurationSubmission
    common.IdentityMappingDestinationDatasourceSubmission
    enrichment.EnrichedEntity
    enrichment.EntityEnrichment
    enrichment.EntityEnrichmentPropertyDefinitions
    exceptions.OAATemplateException
    host.HostCredential
    host.HostEnvironment
    host.HostGranteeType
    host.HostGroup
    hris.HRISEmployee
    hris.HRISGroup
    hris.HRISPropertyDefinitions
    hris.HRISProvider
    idp.CustomIdPApp
    idp.CustomIdPDomain
    idp.CustomIdPGroup
    idp.CustomIdPProvider
    principal.CustomPrincipal
    principal.CustomPrincipalGroup
    principal.CustomPrincipalTenant
    principal.CustomPrincipalUser
    secret_store.IdentityToPermission
    secret_store.PermissionAssignment
    secret_store.SecretStore
    secret_store.SecretStorePermission
    common.append_helper
    common.unique_strs

    Users can also be grouped and assigned permissions with local_groups.

    Veza understands an identity's level access to a resource in terms of raw system permissions in the provider's terms (such as AWS IAM s3:DeleteBucket), and canonical permissions (such asDATA DELETE). This allows Veza to answer the questions: "Who has MERGE permission on production repositories?" and "who can read data from any resource flagged for PII compliance?".

    OAA requires you to map each granular application permission (like "view ticket" or "close ticket") to its corresponding C/R/U/D permission. This enables search and audit of effective and configured access.

    Raw ("System") Permission
    Canonical Permission

    Manage Access

    Metadata Write

    Merge

    Data Write

    Pull

    Data Read

    SaaS apps tend to be role-based, and organizations that follow security best practices will typically restrict the assignment of permissions directly to users. Following standard RBAC concepts, an OAA role represents a collection of permissions which can be scoped to individual resources or specific resource types.

    If permissions granted by a role only apply to specific resource types or sub-resources, create the custom permissions individually and add them to the role in a list:

    Under the custom application OAA schema, users can have direct permissions and role-based permissions to resources. Modeling these role-based permission assignments will enable searches such as "show all users with the maintain role in GitHub."

    Note that “roles” in some apps actually function more like groups (lists of users), in which case they should be modeled using local_groups.

    For payloads where permissions apply for the entire application, you can create a single custom permission for a role, containing all the associated canonical permissions:

    As demonstrated in the OAA PagerDuty connector, this is a quick way to model authorization structures such as:

    Custom Application Role
    Custom App Permission
    Canonical Permission

    Account Owner

    owner

    Data Write, Data Read, Data Delete, Metadata Read, Metadata Write

    Responder

    limited_user

    Data Read, Metadata Read

    Observer

    limited_user

    Data Read, Metadata Read

    Using local_users to describe local and federated identities and service accounts

    local_user

    Map provider permissions to Veza canonical permissions

    Modeling role-based access control

    self.app.add_local_role("Write", ["Pull", "Fork", "Push", "Merge"])
    self.app.add_custom_permission("limited_user", permissions=[OAAPermission.DataRead, OAAPermission.MetadataRead])
    self.app.add_local_role("Responder", unique_id="limited_user", permissions=["limited_user"])

    Custom properties

    not supported

    supported

    Permissions

    none

    declared and bound to identities

    Incremental updates

    not supported

    supported by several templates

    Entity hierarchy

    derived by Veza from the findings

    declared in the payload

    If you are modeling a credential management system rather than the output of a scanner, use the Secret Store template instead. Secret Store describes vaults, entries, and who can read them. Secret Scanner describes credentials that were found where they should not be.

    You submit findings. Veza groups them and creates two entity types:

    • Custom Leaked Secret - one per distinct fingerprint, representing a single credential

    • Custom Leaked Secret Finding - one per submitted finding, representing one occurrence of that credential

    A credential committed to three repositories produces one leaked secret and three findings. Veza also rolls up first and last seen timestamps and a finding count onto the leaked secret.

    To use the secret scanner template, set the template type to secret_scanner when creating a new data provider:

    When a leaked secret has a key_id, Veza looks for an Azure Key Vault secret, key, or certificate whose name equals the key_id. The match isn't case-sensitive. Veza connects the leaked secret to the first matching Key Vault secret, key, or certificate in each Azure subscription where Veza discovers Key Vault objects. A leaked secret without a key_id, or with no matching Key Vault object, isn't connected to a credential.

    Azure Key Vault is the only correlation target for this template. Matching to AWS IAM access keys and to Secret Store entries applies only to leaked secrets found by GitHub Secret Scanning.

    Field
    Type
    Description

    findings

    array

    Required. Array of objects. The only field in the payload

    Veza rejects a payload that contains a field it doesn't recognize, either at the top level or inside a finding.

    Each finding is one occurrence of one credential in one location. Findings are flat: there is no nesting, so every finding repeats the details of the credential it belongs to.

    Field
    Type
    Description

    fingerprint

    string

    Required. Stable identifier for the credential, used to group findings. Two findings sharing a fingerprint describe the same credential

    secret_hash

    string

    Required. A short hash prefix of the credential, for display. Submit this prefix rather than the credential itself

    credential_type

    string

    Required. The kind of credential. See

    Field
    Type
    Description

    source_system

    string

    Required. The scanner that produced the finding

    repository_name

    string

    Required. The repository the credential was found in

    repository_url

    string

    Link to the repository (optional)

    Field
    Type
    Description

    discovered_at

    string

    Required. RFC3339 timestamp for when the scanner found the credential. Veza uses it to derive first and last seen dates for the leaked secret

    scanner_confidence

    integer

    How confident the scanner is, by convention from 0 to 100. A value of 0, or an omitted value, isn't recorded (optional)

    scanner_rule_id

    string

    The scanner rule that matched (optional)

    When several findings share a fingerprint, Veza takes the credential details from the most recently validated one. If that finding leaves key_id, credential_type, or cloud_provider empty, Veza takes the value from another finding in the group. secret_hash and the validation fields come only from the most recently validated finding.

    Four fields hold values that are conventions rather than a set Veza enforces. Any string is accepted.

    Field
    Conventional values

    credential_type

    AWS_ACCESS_KEY, AZURE_CLIENT_SECRET, GCP_SERVICE_ACCOUNT_KEY, GITHUB_PAT, OTHER

    cloud_provider

    AWS, AZURE, GCP, GITHUB, OTHER

    validation_status

    NOT_VALIDATED, VALIDATED_ACTIVE, VALIDATED_INACTIVE

    source_system

    the name of the scanner that produced the finding

    A finding that omits validation_status is recorded as NOT_VALIDATED.

    Readers coming from a vulnerability management tool often look for these. None of them exists in this template:

    • Severity. There is no severity field. scanner_confidence records how sure the scanner is that the match is real, which is a different thing.

    • Remediation or resolution state. validation_status records whether the credential still works, not whether anyone has rotated or revoked it.

    • Assignment and ticketing. There is no assignee, owner, or ticket link.

    • Custom properties. This template accepts no custom_properties and no custom_property_definition.

    For a JSON push, Veza also does not check required fields, either when the push is accepted or when the findings are processed. A finding missing a required field is stored with that value empty. Findings with no fingerprint are all grouped into a single leaked secret, so validate submissions before pushing them. A CSV upload does check fingerprint.

    You can also upload findings as a CSV file, with each row holding one finding. A column mapping on the provider assigns CSV columns to finding fields.

    1. Create the provider with the CSV push type and a column mapping:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{
        "name": "MyScannerCSV",
        "custom_templates": ["secret_scanner"],
        "push_type": "CSV",
        "csv_mapping_configuration": {
          "template_type": "secret_scanner",
          "column_mappings": [
            {"column_name": "fingerprint", "destination_type": "finding", "destination_property": "fingerprint"},
            {"column_name": "hash", "destination_type": "finding", "destination_property": "secret_hash"},
            {"column_name": "type", "destination_type": "finding", "destination_property": "credential_type"},
            {"column_name": "provider", "destination_type": "finding", "destination_property": "cloud_provider"},
            {"column_name": "scanner", "destination_type": "finding", "destination_property": "source_system"},
            {"column_name": "repo", "destination_type": "finding", "destination_property": "repository_name"},
            {"column_name": "path", "destination_type": "finding", "destination_property": "file_path"},
            {"column_name": "line", "destination_type": "finding", "destination_property": "line_number"},
            {"column_name": "key_id", "destination_type": "finding", "destination_property": "key_id"},
            {"column_name": "found_at", "destination_type": "finding", "destination_property": "discovered_at"}
          ]
        }
      }'

      Each mapping names a CSV column in column_name, sets destination_type to finding, and sets destination_property to a finding field. Custom properties aren't supported.

    2. Create a data source on the provider, as for a JSON push.

    3. Upload the file to the data source's :push_csv endpoint, with the CSV contents base64-encoded in csv_data. See .

    These rules apply to the uploaded file:

    • The first row holds the column headers. Header names aren't case-sensitive, and each must be unique.

    • Every column named in the mapping must be present in the header row. Veza ignores columns that aren't mapped.

    • A row without a fingerprint value fails the upload. Veza rejects the file and reports the affected lines.

    • validation_timestamp and validation_response can't be mapped, so a workflow that needs them must push JSON.

    • If discovered_at isn't mapped, Veza records the time of the upload. Timestamp columns accept the .

    As with a JSON push, each upload replaces the contents of the data source.

    To create the OAA provider and push data:

    1. Create the provider with the secret_scanner template type:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"MyScanner","custom_template":"secret_scanner"}'
    2. Create a data source on the provider:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"my_scanner_source"}'
    3. Push the payload to the data source:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data "{\"json_data\": $(jq -Rs . payload.json)}"

      The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.

    Updates follow the same push workflow. Because this template replaces the data source contents on every push, submit the full current set of findings rather than only new ones. Veza removes a credential that the payload no longer lists.

    Payload shape

    one flat array of findings

    Early Access: The Secret Scanner template is available on an Early Access basis. Contact Veza Support to enable it for your organization before you create a provider with this template.

    How it differs from the other templates

    Open Authorization API

    nested entities

    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"MyScanner","custom_template":"secret_scanner"}'
    "findings": [
      {
        "fingerprint": "a3f1c9e77b2d4e8091ac5f6b3d2e8104",
        "secret_hash": "9f2b1c",
        "credential_type": "AWS_ACCESS_KEY",
        "cloud_provider": "AWS",
        "source_system": "EXAMPLE_SCANNER",
        "repository_name": "example-org/billing-service",
        "file_path": "config/settings.yaml",
        "line_number": 42,
        "discovered_at": "2026-09-02T04:15:00Z"
      }
    ]

    Entities Veza creates

    This template does not support . Every push replaces the contents of the data source, so submit the complete set of current findings each time.

    Correlation with Azure Key Vault

    Sample payload

    Two findings for the same credential

    Both findings share a fingerprint, so they resolve to one leaked secret with two occurrences.

    Top-level payload

    Findings

    Identifying the credential

    Locating the finding

    Scanner and validation detail

    Conventional values

    What this template does not carry

    Uploading findings as a CSV file

    The Upload CSV integration in the Veza interface doesn't offer the Secret Scanner template, so create the integration with the API. After that, upload each file with the :push_csv endpoint or with Upload CSV on the integration.

    Creating and updating a secret scanner

    Principal

    Classes for constructing an OAA JSON payload for Custom Principal Submission

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.


    class PrincipalEntityType

    Principal entity types.


    class CustomPrincipal

    CustomPrincipal class for modeling Principal services using OAA Custom Principal Template.

    Principals represent a source of identities (users and groups) to other OAA template types on the same provider.

    Class uses dictionaries to track most components, dictionaries are all keyed by case insensitive string of the entity name

    Args:

    • name (str): Name of Principal Provider

    • principal_type (str): Type descriptor for Principal Provider

    • tenant_id (str): Unique identifier for the tenant

    Attributes:

    • name (str): Name of custom Principal Provider

    • principal_type (str): Type for Principal Provider

    • property_definitions (PrincipalPropertyDefinitions): Custom Property definitions for Principal instance


    Add group to Principal submission

    Arguments:

    • name (str): name for group

    • unique_id (str, optional): unique ID for group

    • group_unique_id (str, optional): unique identifier for group. Used in identity correlation.

    Returns: CustomPrincipalGroup


    Add user to Principal submission

    Arguments:

    • name (str): name for user

    • unique_id (str, optional): unique ID for user

    • email (str, optional): email address for user

    Returns: CustomPrincipalUser


    Return formatted payload as dictionary for JSON conversion and upload


    Tenant model for Custom Principal submission.

    Args:

    • name (str): tenant name

    • unique_id (str): unique ID for tenant

    • tenant_unique_id (str, optional): unique identifier for tenant, usually a URL

    Attributes:

    • name (str): tenant name

    • id (str): unique ID for tenant

    • tenant_unique_id (str): unique identifier for tenant


    Add a new tag to Principal Tenant.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set custom property value for tenant.

    Property name must be defined for tenant before calling set_property().

    Args:

    • property_name (str): Name of property

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Output function for payload.


    User model for CustomPrincipal

    Args:

    • name (str): name for user

    • unique_id (str): unique ID for user

    • email (str, optional): email address for user

    Attributes:

    • name (str): name for user

    • unique_id (str): unique ID for user

    • email (str): email address for user

    • user_unique_id


    Add user to group by group ID.

    Args:

    • group_id (str): ID of group to add user to


    Add an identity to user.

    Args:

    • identity (str): Identity string for user


    Add a new tag to Principal User.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set custom property value for user.

    Property name must be defined for users before calling set_property().

    Args:

    • property_name (str): Name of property

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Function to prepare user entity for payload


    Group model for CustomPrincipal.

    Args:

    • name (str): name of group

    • unique_id (str): unique ID for group

    • property_definitions (PrincipalPropertyDefinitions, optional): Property definitions for custom properties

    Attributes:

    • name (str): name of group

    • id (str): unique ID for group

    • group_unique_id (str): Optional unique identifier for group. Used for identity_unique_id


    Add an identity to group.

    Args:

    • identity (str): Identity string for group


    Add a new tag to Principal Group.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set parent group for hierarchical group structure.

    Args:

    • parent_group_id (str): ID of parent group

    Raises:

    • OAATemplateException: If parent_group_id matches the group's own id


    Set custom property value for group.

    Property name must be defined for groups before calling set_property().

    Args:

    • property_name (str): Name of property

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Function to prepare group entity for payload.


    Model for defining custom properties for CustomPrincipal and its entities (tenant, users, groups).

    Property definitions define the names for additional entity properties and the expected type.

    Attributes:

    • tenant_properties (dict): property definitions for Principal Tenant

    • user_properties (dict): property definitions for Principal users

    • group_properties (dict): property definitions for Principal groups


    Define a group custom property.

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Define a tenant custom property.

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Define a user custom property.

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Returns custom Principal property definitions.


    Validate that a property name has been defined for a given Principal entity.

    Raises exception if property name has not been previously defined for entity

    Args:

    • property_name (str): name of property to validate

    • entity_type (PrincipalEntityType): type of entity custom property is for (TENANT, USER, or GROUP)

    Raises:

    • OAATemplateException: If property name is not defined

    Entity Enrichment

    Template for setting custom property values on existing entities in the Veza authorization graph

    Use this template to set custom property values on existing entities in the Veza authorization graph using the . Unlike other OAA templates that create new entities, the Entity Enrichment template adds metadata to entities that already exist from other integrations.

    Entity enrichment is useful when you have supplemental data about entities that Veza already discovers through native integrations. For example, you might enrich AWS IAM roles with internal compliance metadata, or tag Okta users with cost center information from a custom source.

    The template has two sections:

    • Enriched entity property definitions - declares the custom properties and their types for each entity type being enriched.

    • Enriched entities - the list of existing entities to enrich, with values for each declared property.

    tenant (CustomPrincipalTenant): Tenant model
  • users (dict[CustomPrincipalUser]): Dictionary of CustomPrincipalUser class instances

  • groups (dict[CustomPrincipalGroup]): Dictionary of CustomPrincipalGroup class instances

  • user_unique_id
    (str, optional): unique identifier for user if different than email
    property_definitions
    (PrincipalPropertyDefinitions, optional): Property definitions for custom properties
    property_definitions
    (PrincipalPropertyDefinitions, optional): Property definitions for custom properties
    (str): Optional unique identifier for user. Used for identity_unique_id if set.
  • display_name (str): display name for user

  • is_active (bool): whether user is active

  • created_at (str): date user was created (RFC3339 format)

  • deactivated_at (str): date user was deactivated (RFC3339 format)

  • last_login_at (str): date user last logged in (RFC3339 format)

  • group_type
    (str): type of group
  • parent_group_id (str): ID of parent group for hierarchical groups

  • method __init__

    method add_group

    method add_user

    method get_payload

    class CustomPrincipalTenant

    method __init__

    method add_tag

    method set_property

    method to_dict

    class CustomPrincipalUser

    method __init__

    method add_group

    method add_identity

    method add_tag

    method set_property

    method to_dict

    class CustomPrincipalGroup

    method __init__

    method add_identity

    method add_tag

    method set_parent_group

    method set_property

    method to_dict

    class PrincipalPropertyDefinitions

    method __init__

    method define_group_property

    method define_tenant_property

    method define_user_property

    method to_dict

    method validate_property_name

    cloud_provider

    string

    Required. The provider the credential belongs to. See Conventional values

    key_id

    string

    The credential's public identifier, such as an access key ID. Used to correlate the leaked secret to a credential Veza already knows about (optional)

    file_path

    string

    Required. Path to the file within the repository

    line_number

    integer

    The line holding the credential. Submit it: a finding without this field records line zero

    branch

    string

    The branch the finding was seen on (optional)

    commit_hash

    string

    The commit the credential was found in (optional)

    commit_date

    string

    RFC3339 timestamp for the commit (optional)

    commit_message

    string

    The commit message (optional)

    author_email

    string

    Email address of the commit author (optional)

    author_name

    string

    Name of the commit author (optional)

    finding_context

    string

    Surrounding context for the match, for triage (optional)

    validation_status

    string

    Whether the credential was tested and found to work. See Conventional values (optional)

    validation_timestamp

    string

    RFC3339 timestamp for when validation ran. Also decides which finding's details win when several share a fingerprint (optional)

    validation_response

    string

    Free-form detail from the validation attempt (optional)

    Uploading the Data
    CSV timestamp formats
    finding
    Conventional values
    incremental updates
    __init__(name: 'str', principal_type: 'str', tenant_id: 'str') → None
    add_group(
        name: 'str',
        unique_id: 'str' = None,
        group_unique_id: 'str' = None
    ) → CustomPrincipalGroup
    add_user(
        name: 'str',
        unique_id: 'str' = None,
        email: 'str' = None,
        user_unique_id: 'str' = None
    ) → CustomPrincipalUser
    get_payload() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        tenant_unique_id: 'str' = None,
        property_definitions: 'PrincipalPropertyDefinitions' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        email: 'str' = None,
        property_definitions: 'PrincipalPropertyDefinitions' = None
    ) → None
    add_group(group_id: 'str') → None
    add_identity(identity: 'str') → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        property_definitions: 'PrincipalPropertyDefinitions' = None
    ) → None
    add_identity(identity: 'str') → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_parent_group(parent_group_id: 'str') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__() → None
    define_group_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_tenant_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_user_property(name: 'str', property_type: 'OAAPropertyType') → None
    to_dict() → dict
    validate_property_name(
        property_name: 'str',
        entity_type: 'PrincipalEntityType'
    ) → None
    {
      "findings": [
        {
          "fingerprint": "a3f1c9e77b2d4e8091ac5f6b3d2e8104",
          "secret_hash": "9f2b1c",
          "credential_type": "AWS_ACCESS_KEY",
          "cloud_provider": "AWS",
          "source_system": "EXAMPLE_SCANNER",
          "repository_name": "example-org/billing-service",
          "repository_url": "https://git.example.com/example-org/billing-service",
          "file_path": "config/settings.yaml",
          "line_number": 42,
          "commit_hash": "4b7c2a91d8e3f560172bc4a9e8d3f102",
          "branch": "main",
          "author_email": "alice@example.com",
          "author_name": "Alice Chen",
          "commit_date": "2026-08-14T16:22:10Z",
          "commit_message": "Add billing service configuration",
          "scanner_confidence": 90,
          "scanner_rule_id": "aws-access-key-id",
          "key_id": "AKIAIOSFODNN7EXAMPLE",
          "discovered_at": "2026-09-02T04:15:00Z",
          "validation_status": "VALIDATED_ACTIVE",
          "validation_timestamp": "2026-09-02T04:16:30Z"
        },
        {
          "fingerprint": "a3f1c9e77b2d4e8091ac5f6b3d2e8104",
          "secret_hash": "9f2b1c",
          "credential_type": "AWS_ACCESS_KEY",
          "cloud_provider": "AWS",
          "source_system": "EXAMPLE_SCANNER",
          "repository_name": "example-org/deploy-scripts",
          "file_path": "scripts/deploy.sh",
          "line_number": 7,
          "branch": "main",
          "discovered_at": "2026-09-02T04:15:00Z",
          "validation_status": "VALIDATED_ACTIVE"
        }
      ]
    }
    To use the entity enrichment template, set the template type to entity_enrichment when creating a new data provider:
    Field
    Type
    Description

    enriched_entity_property_definitions

    array

    List of for each entity type

    enriched_entities

    array

    List of to enrich with property values

    Each entry declares the custom properties that will be added to a specific entity type, along with their data types. Property types determine how Veza stores and indexes values. For example, TIMESTAMP properties enable relative date filters in queries (such as "last 90 days").

    Field
    Type
    Description

    entity_type

    string

    Veza entity type to enrich (e.g., AwsIamRole, OktaUser)

    enriched_properties

    dictionary

    Map of property names to their types. See

    Type
    Description

    STRING

    Text value

    NUMBER

    Numeric value (integer or float)

    BOOLEAN

    true or false

    TIMESTAMP

    Date/time value. Enables relative date filters in Veza queries

    STRING_LIST

    List of string values

    The list of existing entities to enrich with property values. Each entity must appear exactly once with all properties that should be set. Including an entity with no properties clears all enriched property values from that entity. Only entities in the list are updated; other entities are not affected.

    Field
    Type
    Description

    type

    string

    Veza entity type (must match an entity_type in the property definitions)

    id

    string

    Veza unique ID for the entity. For AWS entities, this is the ARN. Each entity must appear only once in the list

    data_source_id

    string

    Veza data source ID for the entity. For AWS, combine the account ID with the data source type (e.g., 339083562601:awsiam)

    To create the OAA provider and push enrichment data:

    1. Create the provider with the entity_enrichment template type:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"Enrichment Provider","custom_template":"entity_enrichment"}'
    2. Create a data source on the provider:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"Enrichment Data Source"}'
    3. Push the enrichment payload to the data source:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data "{\"json_data\": $(jq -Rs . payload.json)}"

      The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string. See for compression options.

    Updates follow the same push workflow. Each push replaces the enrichment data for the entities included in the payload. Entities not included in the push are not affected.

    Property values vs. property definitions: You can clear a property value by omitting its key in a subsequent push, or by including the entity with an empty properties object. This clears the stored value but does not remove the property definition from the entity type. Once a property name is defined for an entity type, the definition persists in the graph and cannot be removed.

    Provider deletion: Deleting an enrichment provider does not remove enrichment data from the Veza graph. Data pushed through the provider remains associated with the enriched entities after the provider is deleted. Contact Veza support if you need to fully remove enrichment data from the graph.

    The Entity Enrichment template sets arbitrary custom properties via API push. This is distinct from Enrichment Rules, which are UI-configured rules that set a fixed set of built-in Veza classification attributes (identity type, owner, privileged status, and criticality) at extraction time. Use this template when you need to attach custom metadata beyond those built-in attributes. For assigning entity owners (a built-in attribute), see OAA Entity Owners.

    Open Authorization API
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"My Enrichment Provider","custom_template":"entity_enrichment"}'
    "enriched_entity_property_definitions": [
      {
        "entity_type": "AwsIamRole",
        "enriched_properties": {
          "my_company_id": "STRING",
          "is_compliance_validated": "BOOLEAN"
        }
      }
    ]
    "enriched_entities": [
      {
        "type": "AwsIamRole",
        "id": "arn:aws:iam::339083562601:role/Administrator",
        "data_source_id": "339083562601:awsiam",
        "properties": {
          "my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
          "is_compliance_validated": true
        }
      }
    ]

    Sample payload

    AWS IAM enrichment example

    This example enriches AWS IAM roles with internal compliance metadata and AWS IAM users with a purpose description.

    Top-level payload

    Enriched entity property definitions

    Property definition fields

    Supported property types

    Enriched entities

    Enriched entity fields

    Creating and updating enrichment data

    Limitations

    Incremental Updates

    Modifying custom providers using a partial OAA payload

    When developing your OAA integration, whether to implement incremental updates depends on your use case. If you don't have a convenient way to track provider-side changes, it is typically easier to do a full extraction and metadata push, to not miss changes within the app or IdP.

    After the initial metadata push, you can modify, add, or remove OAA entities, permissions, and properties without needing to submit the full payload each time. A first push can't be an incremental update.

    An incremental update is specified by setting "incremental_change": true in the json_data push payload and adding an update operation for each entity to change. Most payload objects support incremental update operations:

    Custom Application
    Custom Identity Provider

    The operation field indicates the change to make. Valid operations are:

    • "add", "modify", "delete" to create, change, or remove an entity.

    • "add_resource", "delete_resource" to modify resources in applications, permissions and role scopes.

    • "add_tag"

    The object to update must contain an ID (name or identity) and the properties to create or modify. An error response will provide more details if an operation is invalid or unavailable.

    See the sample payload below for .

    • When modifying dynamic properties, all five properties must be present.

    • add and modify can't be used on the same object. For example, to update both tags and properties on an entity, use:

    The following JSON example for includes a range of update operations. Note that when modifying tags, only include the identity and tags (no other properties such as manager_id can be present).

    OAA Entity Owners

    Setting Entity Owners in OAA Payloads

    Early Access: OAA Entity Owners functionality is currently in Early Access for automatic assignment of entity ownership during OAA payload submission. Please contact our customer success team to enable this feature for your environment.

    Overview

    OAA supports setting Entity Owners on OAA Entities as part of the submission for some templates. This enables a single operation to submit the OAA Entity and its owner.

    Entity Owners enable automated assignment and accountability in access management and other workflows:

    • Owners can be used by Access Workflows for automatic assignment of review rows

    • Assigning owners for entities that represent non-human identities enables visibility into those users on the Non-Human Identities (NHI) overview page.

    • If Veza assigns a Risk Score to the entity, an owner assignment can help identify the user best able to remediate the risk.

    Currently supported OAA Templates and entity types for Entity Owners:

    Application Template:

    • Application (owners can be set at the application level itself)

    • Users

    • Groups

    • Roles

    • Resources

    Requirements:

    Entity Owners must be a User entity type from an Identity Provider integration enabled in Veza. If a is configured, the owner must be a user entity from the Global IDP.

    Identity-provider application entities (such as OktaApp and AzureADEnterpriseApplication) also support entity owners, but owners are not set in the OAA payload. See for the full list and assignment methods.

    Use the owners property on supported entities to specify entity owners as an array of objects.

    Attribute
    Value

    For example, setting the owner on a role may look like the following:

    For custom identity providers, you will need to determine the correct owner_type format to identify the entities in Veza Graph. You can find this information through the Veza UI or using an API request:

    In the Veza UI:

    1. Go to Access Visibility > Graph

    2. Search for a user from your custom identity provider

    3. Click on the user to open the sidebar and choose Basic Actions > View Details

    4. The entity type is displayed in the user details (e.g., "OAA.Custom_IDP.IDPUser")

    Alternately, you can use GET /api/v1/providers/custom to list all custom providers and their idp_type values. The owner_type format should be OAA.{idp_type}.IDPUser

    See the table below for common IdP types and corresponding owner entity types:

    If an Owner entry is malformed, references an unsupported owner type, or conflicts with the Global IDP setting a Field Violation error will be returned and the OAA payload will be rejected.

    If an owner identity cannot be found, a warning will be returned with the successful response and the OAA payload will be accepted and processed with the unknown owner(s) being ignored.

    Entity owners must originate from the primary Global IdP source. Users from cannot be used as entity owners.

    After submitting an OAA payload with entity owners, verify the assignment by locating the entity in Query Builder or Graph Search. You can then configure to use these owners in access review workflows.

    properties

    dictionary

    Map of property names to values. Keys must be defined in the property definitions, and values must match the declared type. Omitting a key that is defined in the property definitions removes that property value from the entity

    OAA API Operations
    property definitions
    entities
    supported types
    {
      "enriched_entity_property_definitions": [
        {
          "entity_type": "AwsIamRole",
          "enriched_properties": {
            "my_company_id": "STRING",
            "company_purpose": "STRING",
            "is_compliance_validated": "BOOLEAN"
          }
        },
        {
          "entity_type": "AwsIamUser",
          "enriched_properties": {
            "company_purpose": "STRING"
          }
        }
      ],
      "enriched_entities": [
        {
          "type": "AwsIamRole",
          "id": "arn:aws:iam::339083562601:role/Administrator",
          "data_source_id": "339083562601:awsiam",
          "properties": {
            "my_company_id": "DCFB16CD-A044-4787-9165-1C926221F887",
            "company_purpose": "Built in Admin role",
            "is_compliance_validated": true
          }
        },
        {
          "type": "AwsIamRole",
          "id": "arn:aws:iam::650251689811:role/andrew_s3_all",
          "data_source_id": "339083562601:awsiam",
          "properties": {
            "my_company_id": "A3F40BAC-1871-4EFC-A0EE-CD77E3F513C27",
            "company_purpose": "Some role for Andrew",
            "is_compliance_validated": false
          }
        },
        {
          "type": "AwsIamUser",
          "id": "arn:aws:iam::339083562601:user/andrew",
          "data_source_id": "339083562601:awsiam",
          "properties": {
            "company_purpose": "Engineering service account"
          }
        }
      ]
    }
    ,
    "delete_tag"
    to update a tag without altering the entity.

    application, user, group, role, permission, role_assignments

    domain, group, user

    Notes

    Sample payload

    more examples
    custom application

    Access Credentials

    Use this exact node type as your owner_type value

    OneLogin

    "OneLogin"

    OneLoginUser

    AWS IAM Identity Center

    "AwsSso"

    AwsSsoUser

    Google Workspace

    "Google"

    GoogleWorkspaceUser

    Custom LDAP

    "company_ldap"

    OAA.company_ldap.IDPUser

    Custom Identity Provider

    "custom_idp"

    OAA.custom_idp.IDPUser

    external_id

    The ID of the owner from the IDP. External ID supports the same lookup attributes as identities

    owner_type

    The node type of the owner (case insensitive). For custom identity providers, use format OAA.{idp_type}.IDPUser, where {idp_type} is the value specified when creating the custom IdP provider. To find your idp_type value, use the List Custom Providers API. The attribute is optional when the Global IDP is configured

    primary

    If true, user is the primary owner, defaults to false

    Provider Type

    idp_type Value

    owner_type Format

    Standard Okta

    "Okta"

    OktaUser

    Standard Azure AD

    "AzureAD"

    AzureADUser

    Active Directory

    "ActiveDirectory"

    ActiveDirectoryUser

    Ping Identity

    "PingOne"

    Supported Templates and Entity Types

    Entity Owner Entry

    Example Usage

    Owner Type Values

    Warnings and Errors

    Next Steps

    Global Identity provider
    Supported entity types for owner assignment
    alternate manager lookup sources
    automatic reviewer assignment

    PingOneUser

      "resources": [
        {
          "name": "resource1",
          "resource_type": "type1",
          "tags": [
            {
              "key": "keyDelta1",
              "value": "valDelta1"
            }
          ],
          "operation": "add_tag"
        },
        {
          "name": "resource1",
          "resource_type": "type1",
          "operation": "modify"
        }
      ]
    {
      "incremental_change": true,
      "applications": [
        {
          "name": "Controller1",
          "application_type": "WebServer",
          "description": "The base web server",
          "local_users": [
            {
              "name": "LUser1",
              "identities": [
                "localuser1@company.com"
              ],
              "operation": "delete"
            },
            {
              "name": "LUser1",
              "identities": [
                "localuser1Mod@company.com"
              ],
              "operation": "add"
            }
          ],
          "local_groups": [
            {
              "name": "LGroup1",
              "identities": [
                "localgroup1@company.com"
              ],
              "tags": [
                {
                  "key": "groupTag2Key",
                  "value": "groupTag2Value"
                }
              ],
              "operation": "add_tag"
            }
          ],
          "local_roles": [
            {
              "name": "LRole2",
              "permissions": [
                "FULL"
              ],
              "operation": "delete"
            }
          ],
          "resources": [
            {
              "name": "resource1",
              "sub_resources": [
                {
                  "name": "sub1b",
                  "operation": "delete"
                }
              ],
              "operation": "modify"
            }
          ]
        }
      ],
      "permissions": [
        {
          "name": "Just Access",
          "operation": "modify"
        },
        {
          "name": "NonData",
          "PermissionType": [
            "NonData"
          ],
          "operation": "add"
        },
        {
          "name": "READ",
          "permission_type": [
            "DataRead"
          ],
          "operation": "delete"
        },
        {
          "name": "READ",
          "permission_type": [
            "DataRead"
          ],
          "operation": "add"
        }
      ],
      "identity_to_permissions": [
        {
          "identity": "testuser1@company.com",
          "identity_type": "IDP",
          "role_assignments": [
            {
              "application": "Controller1",
              "role": "LRole1",
              "apply_to_application": true,
              "operation": "delete"
            },
            {
              "application": "Controller1",
              "role": "LRole2",
              "resources": [
                "resource1",
                "resource1.sub1a.sub2b"
              ],
              "operation": "add"
            }
          ]
        },
        {
          "identity": "testuser3@company.com",
          "identity_type": "IDP",
          "role_assignments": [
            {
              "application": "Controller1",
              "role": "LRole1",
              "resources": [
                "resource1.sub1b",
                "resource1.sub1c"
              ],
              "operation": "delete_resource"
            },
            {
              "application": "Controller1",
              "role": "LRole1",
              "resources": [
                "resource1.sub1a"
              ],
              "operation": "add_resource"
            }
          ],
          "application_permissions": [
            {
              "application": "WebServer2",
              "permission": "Just Access",
              "operation": "delete"
            }
          ]
        }
      ]
    }
    {
        "external_id": "some_user@example.com",
        "owner_type": "OktaUser",
        "primary": true
    }
          "local_roles": [
            {
              "name": "User Admin",
              "permissions": [
                "view_all",
                "manage_users"
              ],
              "owners": [
                {
                  "external_id": "some_user@example.com",
                  "owner_type": "OktaUser",
                  "primary": true
                }
              ]
            }
          ]

    Okta SSO Last Login Enrichment

    Enrich OAA custom application users with SSO last login timestamps from Okta

    Early Access: This feature is not enabled by default. Veza Support enables Okta SSO last login enrichment for your tenant on request.

    Veza can enrich custom application (OAA) users with SSO last login timestamps by correlating Okta sign-in activity with your application's local users. When enabled, each local user in the Veza graph gains a sso_last_login_at property showing the last time that user accessed the application through Okta SSO.

    This is useful for identifying dormant accounts, auditing access patterns, and supporting access reviews.

    How it works

    1. You specify the Okta Application ID (okta_app_id) for your custom application.

    2. For this enrichment, Veza matches your OAA local users to Okta users using the matching property you set with the Veza API in Step 2.

    3. On each data push, Veza looks up Okta SSO activity for your application and writes the last login timestamp to matching local users.

    Enrichment runs in the OAA service after data submission. If Okta activity data is unavailable, the push completes normally without SSO timestamps, and no data is lost.

    Veza queries Okta activity at push time, stores the result with the submission, and replays that stored result on later parses without querying again. A sso_last_login_at value therefore reflects the most recent push of that application, not the most recent parse or Okta extraction.

    After an Okta audit log extraction completes, push the application again to include the new activity. A scheduled parse of the application does not retrieve it, because the parse replays the stored result. For a CSV integration, upload the file again. A second extraction of the Okta integration is not required: the regular Okta extraction only places the Okta users in Access Graph so that they can be matched.

    • An active Okta integration in Veza with . Audit log data is the source for sso_last_login_at timestamps.

    • A custom application (OAA) integration, using either API push or CSV upload.

    • The Okta App ID (okta_app_id) set on the application, described in Step 4.

    Ask Veza Support to enable Okta SSO last login enrichment for your tenant. You can't enable it yourself.

    Configure which Okta user property Veza uses to correlate Okta users with your application's local users. You can set this yourself using the Veza API.

    The string you pass as value specifies which OktaUser attribute to use for identity mapping. The attribute value on each Okta user must match the identities field on the linked OAA local users.

    • For example, if local users have identities: ["jane.doe@company.com"] and OktaUser nodes have login: "jane.doe@company.com", use login.

    • Custom attributes (e.g., customprop_employee_id) are also supported.

    To set the property, send a PUT request with an API key that has the admin or system_monitoring role:

    Replace <okta_user_property_name> with the OktaUser property to match on (e.g., login, email, or a custom attribute such as customprop_idx_uid).

    To verify the current value:

    Look for the okta_sso_user_matching_property key in the response.

    Locate the Okta Application ID (0oa…) for the application you want to enrich:

    1. Log in to your Okta Admin Console.

    2. Navigate to Applications > Applications.

    3. Select the application.

    4. Copy the application ID from the URL (format: 0oaXXXXXXXXXXXXXXXX).

    The method depends on how you push data to Veza.

    Add the okta_app_id field to your application payload at the application level:

    • okta_app_id (application level): Your Okta Application ID.

    • identities (user level): One or more identity strings matched against the configured Okta user property.

    1. Navigate to Integrations > Custom Application (CSV).

    2. Enter your Okta Application ID in the Okta App ID field in the application configuration form.

    3. Upload your CSV as usual, ensuring users have identity values that match their Okta profiles.

    After pushing data, verify enrichment is working:

    1. Open Query Builder in Veza.

    2. Query for your custom application's local users.

    3. Check the sso_last_login_at column on user nodes.

    Users whose identities matched an Okta user with SSO activity for your application will have a sso_last_login_at timestamp. Users without a match (such as service accounts or users not in Okta) will not have this property — this is expected.

    • Matching is case-insensitive. Jane.Doe@company.com and jane.doe@company.com are treated as the same identity.

    • First match wins. If a user has multiple identities, the first one that matches an Okta user is used.

    • Enrichment is non-blocking. If Okta data is unavailable, the push completes without SSO timestamps. No data is lost.

    Issue
    Possible cause
    Resolution

    Using OAA Templates

    How to use the Application Template to represent various types of application

    The OAA Application template allows for representing the basic elements of an application and is flexible to allow for multiple different patterns.

    The custom application template provides a framework for describing:

    • Who: Users, Groups, and other identities

    • What: Application, resources, sub-resources

    • How: Permissions, canonical mappings, roles, authorization

    Application Example

    Application

    The Application itself is the first entity as part of the Application submission. The application has a name and a type. The name can be specific such as "West Production" and the type is typically the vendor, technology, or product such as "GitLab". Veza will group the rest of the entities by the application type such as "GitLab Users" across all instances of an application type, however, entities will only be directly associated with the application they are submitted with. Applications additionally can have custom properties assigned to further enrich the data. This can be especially useful to distinguish between multiple instances of an application type.

    Local Users

    The Local User object represents the local user of the application. It can store application-specific information such as the identifier, name, active status, last login time, and custom properties specific to the application. An external Identity can be associated with the user, enabling Veza to connect the source Identity Provider (IdP). This creates a connection in Access Graph between the application user and a source identity such as Okta or Active Directory. Users can be added to groups, or have roles and permissions directly assigned.

    Local Groups

    Local Groups represent a collection of users. Groups can store additional metadata about the group to support search and filters. Groups can also contain other groups, to model applications that support nested groups. Groups can have role and permission assignments in the application.

    Local Roles

    Local Roles represent a collection of permissions within an application. When a user or group is assigned a role, that user or group is assigned all the permissions from the role. Like other entities, roles can contain additional properties to enrich the metadata of the role, such as description or application-specific attributes.

    Permissions

    OAA allows for expressing the permissions of the application in its own terms. In the Application Template, permissions are defined by application-specific terms such as "Close Ticket" or "Approve User". These permissions will also allow for setting corresponding Veza Canonical Permissions such as "Data Read", "Data Write", or "Metadata Read". This enables search and filters across permissions using CRUD-like equivalents.

    Available Canonical Permissions: - DataRead - DataWrite - DataCreate - DataDelete - MetadataRead - MetadataWrite - MetadataCreate - MetadataDelete - NonData - Uncategorized

    Resources

    Resources can be used to model components within applications that users can be assigned roles or permissions on. For example, an OAA resource may be used to model a Project in an application like Jira. Users can have different roles in different projects, by assigning the correct users or groups their respective roles on the resources. Each resource has a Type which Veza uses when displaying and searching the resources for an application. Applications can have multiple types of Resources. Like other entities, resources can have properties containing additional resource metadata.

    Below are some examples of how applications may be modeled in OAA. These examples have all been implemented using the Application template.

    PagerDuty is an example of an application where users can have roles at the application level (global roles) but also within the PageDuty Teams that a user is a member of. Understanding which Users are part of which Teams and what level of access they have in those Teams is important for reviewing access in an application like PagerDuty. The OAA Application template can be used to model this type of application using the following mappings.

    PagerDuty Entity
    OAA Application
    Notes

    With this model, Veza can show the levels of access users have within the overall Application and their individual Teams. In this example, we can see the User Gary Ward has the Role "Restricted Access" in the PagerDuty Application, and the "Observer" Role in the "Support" Team Resource.

    Python Code for the can be referenced on the Veza GitHub

    GitLab is a good example of a more complex application that can be modeled using the Veza OAA Application Template. By correctly modeling the applications, Veza can show which users have access to GitLab Groups and Projects to show details beyond just "who has access to GitLab?"

    GitLab
    OAA Application
    • Each GitLab User is represented with the Application Local User. GitLab assigns each user a unique ID number to each user, using this as the ID for the Local User makes it easier when associating groups and roles to Projects later. The Local User also allows for setting properties to represent the user's state such as is_active or last_login_at, custom properties to represent GitLab-specific properties can also be utilized like if the user is licensed or not. The identity for the Local User is set to enable OAA connection to source Identity Providers configured in Veza.

    • A GitLab Group represents both a collection of Users, a collection of Projects, and possibly other sub-groups. This is a good example of where some mapping needs to be done to represent GitLab using the Application Template. Since GitLab Users have a specific role in the GitLab Group, it is correct to represent the GitLab Group as an OAA Resource. Members are assigned an

    Python Code for the can be referenced on the Veza GitHub

    File System

    Template for modeling file systems with servers, mounts, folders, and permissions

    Use this template to model file systems and file storage platforms using the . The File System template captures which identities hold which permissions on servers, mounts, and folders, for systems that are not covered by a native Veza integration.

    The template models a hierarchical structure:

    • Server - a file server or storage account hosting one or more mounts

      • Mount - a share, drive, or volume on that server

    Local Resource

    To represent the User's role in the Team

    Team Role

    Local Role

    Applied to the Team Resource

    OAA Local Role
    to the
    Resource
    that represents the
    GitLab Group
    , denoting their level of access (Owner, Developer, Guest, and so on). Veza can return all the members of a
    GitLab Group
    by querying for the relation between the
    OAA User
    and the
    OAA Resource
    . Additionally, the role within the
    GitLab Group
    is preserved by the
    OAA Role
    .
  • GitLab Roles are assigned to users or Groups as part of a Group or Project. GitLab is an example of an application with fixed roles where the roles and behaviors are coded directly into the application. For the OAA Application Template, the corresponding Local Roles are also coded directly into the connector by reviewing the GitLab documentation on available roles and the permissions associated with the roles. It is not always necessary to capture every Permission as part of the Local Role. Which permissions are important and how much detail is needed will be determined by the queries you intend to run, and the scope of Access Reviews that will be conducted in Veza.

  • GitLab Projects are also represented as an OAA Sub-Resource with the type set to Project. The Project Sub-Resource is added to the corresponding Group resource. Local User and Local Groups can be assigned roles on the project based on their direct assignments. In the case of GitLab, permissions can be inherited from above. This is an optional behavior for permissions, which can be set to automatically apply to sub-resources, or only apply directly to the assigned resources. Additionally, permissions can be set to apply to certain types of resources so that roles can be used across resources and only the correct permissions will be applied.

  • User

    Local User

    Team

    Local Group

    To group the Users

    Application Role

    Local Role

    Applied to the Application

    User

    Local User

    Group

    Resource

    Project

    Sub Resource

    Examples

    PagerDuty

    GitLab

    PagerDuty connector
    GitLab connector
    Users example
    Users example
    PagerDuty App
    GitLab App

    Team

    The tenant configuration okta_sso_user_matching_property set to the Okta user property that holds your join key, described in Step 2. Veza uses this one property tenant-wide; it does not search every property on the Okta profile.
  • identities values on your OAA local users that equal that Okta property's value for each user.

  • Timestamps reflect Okta access pattern data. The sso_last_login_at value comes from Okta's recorded activity for your specific application.

    No Okta SSO activity

    The user may not have accessed this application through Okta SSO

    sso_last_login_at missing on specific users

    No audit log activity for the app

    Check Audit Logs for entries where the identity (GPID) accessed the OktaApp matching your okta_app_id. Enrichment only occurs when Veza has recorded SSO activity for that identity and application. This requires on the Okta integration.

    Okta App ID field not visible in CSV form

    Feature not enabled for the tenant

    Contact Veza support to enable the feature

    sso_last_login_at is older than the sign-in Okta reports

    No push has run since that sign-in

    Veza refreshes these values only during a push, even when the data source was parsed more recently or the Okta integration extracted activity more recently. Push the application again. For a CSV integration, upload the file again. See

    curl -X PUT \
      "https://<tenant>.vezacloud.com/api/private/namespaces/integrations/configurations/okta_sso_user_matching_property" \
      -H "Authorization: Bearer <api_key>" \
      -H "Content-Type: application/json" \
      -d '{"value": "<okta_user_property_name>"}'
    curl -s "https://<tenant>.vezacloud.com/api/private/namespaces/integrations/configurations?page_size=100" \
      -H "Authorization: Bearer <api_key>"
    {
      "name": "My Application",
      "application_type": "my_app_type",
      "okta_app_id": "0oaABCDEF1234567890",
      "local_users": [
        {
          "unique_id": "jdoe",
          "name": "Jane Doe",
          "identities": ["jane.doe@company.com"],
          "email": "jane.doe@company.com"
        }
      ]
    }

    sso_last_login_at not appearing on any users

    Feature not enabled for the tenant

    Ask Veza Support to confirm Okta SSO last login enrichment is enabled for your tenant

    sso_last_login_at not appearing on any users

    Matching property not configured

    Use the API in Step 2 to set okta_sso_user_matching_property, or contact Veza support to verify it is set

    sso_last_login_at missing on specific users

    Identity mismatch

    Ensure the user's identities values match the OktaUser property values (check casing and email format)

    When enrichment runs

    SSO last login matching is separate from identity correlation in Access Graph.

    The property you configure here governs the sso_last_login_at enrichment only. The relationship between a local user and an Okta user is created by automatic identity matching, which compares a fixed set of Okta attributes, or by a configured identity mapping. Pointing okta_sso_user_matching_property at a custom attribute does not create that relationship.

    Prerequisites

    Holding the same value on both sides is not sufficient on its own. For example, when Okta users and your CSV users both carry an employee ID, enrichment still requires okta_sso_user_matching_property to point at the Okta employee ID property and the same employee ID to be present in each local user's identities value.

    Setup

    Step 1: Request feature enablement

    Step 2: Set the matching property configuration

    /api/private/ endpoints are not part of the public API contract and may change between releases.

    Step 3: Find your Okta application ID

    Step 4: Add the Okta app ID to your custom application

    API push (JSON)

    CSV upload

    The Okta App ID field in the CSV configuration form is only visible after Veza Support enables Okta SSO last login enrichment for your tenant.

    Verifying enrichment

    Behavior notes

    Troubleshooting

    audit logs enabled

    sso_last_login_at missing on specific users

    Folder - a directory within a mount, which can contain further folders

  • Permissions - a catalog of named permissions declared once and referenced wherever granted

  • Identity-to-permission bindings - map identities to permissions on a specific mount or folder

  • A custom property definition can define additional properties for servers, mounts, folders, and permissions.

    To use the file system template, set the template type to file_system when creating a new data provider:

    This template has two submission modes, and a single payload must use one or the other. The mode is selected by which fields you send, not by a flag.

    Mode
    Send
    Do not send
    Use when

    Server mode

    server and mounts

    folders

    A collector can see the server and enumerate its shares

    Folder mode

    folders and server_unique_id

    server and mounts

    A collector enumerates directories within one share

    Veza rejects a payload that mixes them. Sending server and folders together, sending mounts without server, or sending server with an empty mounts array all fail validation.

    Most integrations use both modes across separate data sources on the same provider: one data source submits the server and its mounts, and further data sources submit the folders for each mount. A folder joins its mount by setting parent_id to that mount's unique_id. Veza connects the two across data sources after both have been pushed, so order does not matter. A folder whose mount has not been submitted yet remains unattached until it is.

    Field
    Type
    Description

    file_system_type

    string

    Required. Type descriptor for the file system, for example Windows File Server or Google Drive. Applied as a searchable property and used to interpret folder paths

    server_unique_id

    string

    Required in folder mode. The unique_id of the server these folders belong to

    server

    object

    The object. Sending this field selects server mode

    identity_provider_types accepts any, active_directory, azure_ad, custom, google_workspace, okta, and one_login.

    The server represents the machine or storage account hosting the mounts. Send it only in server mode.

    Field
    Type
    Description

    unique_id

    string

    Required. Identifier for the server, unique within the payload. Maximum 512 characters

    name

    string

    Required. Display name for the server

    description

    string

    Description shown in Veza entity details (optional)

    A mount is a share, drive, or volume on the server. Mounts carry identity bindings and can contain folders.

    Field
    Type
    Description

    unique_id

    string

    Required. Identifier for the mount, unique within the payload

    name

    string

    Required. Display name for the mount

    description

    string

    Description shown in Veza entity details (optional)

    A folder is a directory within a mount. Folders nest by referencing another folder, and attach to a mount by referencing the mount. Send them only in folder mode.

    Field
    Type
    Description

    unique_id

    string

    Required. Identifier for the folder, unique within the payload

    name

    string

    Required. Display name for the folder

    description

    string

    Description shown in Veza entity details (optional)

    Setting inherit_parent_permissions to true copies the parent's identity_to_permissions onto the folder, but only when the folder declares no bindings of its own. The rules are:

    • A folder with its own identity_to_permissions keeps them. The flag is ignored.

    • A folder with an empty identity_to_permissions and the flag set to true receives a copy of its parent's bindings.

    • A folder whose parent is not present in the same payload receives nothing, even with the flag set.

    Inheritance is resolved when the payload is received, so the resulting bindings appear on the folder itself rather than being computed at query time. A folder that should show no access at all can set the flag to false and omit the bindings.

    The permission catalog declares each permission once, at the top level of the payload. Mounts and folders then reference permissions by name.

    Field
    Type
    Description

    name

    string

    Required. Serves as both the permission's identifier and its display name. There is no separate ID field. Maximum 512 characters

    description

    string

    Description shown in Veza entity details (optional)

    permission_type

    array

    Required, and must not be empty. One or more canonical permission types. See the list below

    permission_type accepts DataRead, DataWrite, DataCreate, DataDelete, MetadataRead, MetadataWrite, MetadataCreate, MetadataDelete, NonData, and Uncategorized. These are the canonical types Veza uses to calculate effective permissions, and they are the same set used by the other custom templates.

    Permission names are matched without regard to letter case or spaces, so Full Control, full control, and full_control refer to the same permission. Declaring two permissions whose names differ only in case or spacing is an error.

    identity_to_permissions sits on mounts and folders, and maps each identity to the permission names it holds on that resource:

    Every permission name must appear in the top-level permissions catalog. A name that does not resolve fails validation.

    This template defines no local users or groups. The keys are identities belonging to an identity provider, and Veza matches them after the push against the integrations for the identity provider types you declared. Matching is case-insensitive, but the attributes a key can match depend on the identity provider:

    Identity provider type
    Users match on
    Groups match on

    active_directory

    User principal name, account name, distinguished name, or email address

    Distinguished name only

    azure_ad

    User principal name, onPremisesSamAccountName, identity provider ID, or email address

    Name, principal name, or identity provider ID

    okta

    Login, identity provider ID, or email address

    Name or identity provider ID

    An Active Directory group must be keyed by its distinguished name. A share whose access control list holds DOMAIN\FinanceAdmins is submitted as CN=FinanceAdmins,OU=Groups,DC=example,DC=com, not as FinanceAdmins.

    An identity that matches nothing yields a permission with no identity attached to it. That can mean the identity does not exist, or that the integration owning it has not been added yet.

    Custom properties allow you to attach additional metadata to file system entities. Define properties in the custom_property_definition object, then set values on individual entities.

    Scope
    Description

    server_properties

    Custom properties for server entities

    mount_properties

    Custom properties for mount entities

    permission_properties

    Custom properties for permission entities

    folder_properties

    Custom properties for folder entities

    Property values must match their declared type. Supported types are described in Custom properties.

    Property names are stored in lowercase, so two names differing only in letter case are an error. Each entity accepts at most 50 custom properties. Setting a custom property that the definition does not declare fails the push.

    To create the OAA provider and push data:

    1. Create the provider with the file_system template type:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"MyFileSystem","custom_template":"file_system"}'
    2. Create a data source on the provider:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"my_file_server"}'
    3. Push the payload to the data source:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data "{\"json_data\": $(jq -Rs . payload.json)}"

      The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.

    When a file system spans both modes, create one data source for the server and its mounts, and a further data source for each set of folders. Push each independently.

    Updates follow the same push workflow. Veza processes the full payload and replaces the contents of that data source. Unrecognized fields cause the push to fail, so remove any field this template does not define.

    Open Authorization API
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"MyFileSystem","custom_template":"file_system"}'
    "server": {
      "unique_id": "fs-prod-01",
      "name": "fs-prod-01.example.com",
      "description": "Primary file server",
      "custom_properties": {},
      "tags": []
    }
    "mounts": [
      {
        "unique_id": "finance-share",
        "name": "Finance",
        "description": "Finance department share",
        "created_at": "2025-03-14T00:00:00Z",
        "updated_at": "2025-09-01T00:00:00Z",
        "identity_to_permissions": {
          "CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"]
        },
        "custom_properties": {},
        "tags": []
      }
    ]
    "folders": [
      {
        "unique_id": "finance-reports",
        "name": "Reports",
        "path": "\\\\fs-prod-01\\Finance\\Reports",
        "parent_id": "finance-root",
        "inherit_parent_permissions": true,
        "created_at": "2025-03-14T00:00:00Z",
        "updated_at": "2025-09-01T00:00:00Z",
        "identity_to_permissions": {},
        "custom_properties": {},
        "tags": []
      }
    ]
    "permissions": [
      {
        "name": "Full Control",
        "description": "Read, write, and change permissions",
        "permission_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"],
        "custom_properties": {},
        "tags": []
      }
    ]
    "identity_to_permissions": {
      "CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"],
      "alice@example.com": ["Read"]
    }
    "custom_property_definition": {
      "server_properties": {
        "datacenter": "STRING"
      },
      "mount_properties": {
        "quota_gb": "NUMBER",
        "encrypted": "BOOLEAN"
      },
      "permission_properties": {},
      "folder_properties": {
        "owner": "STRING"
      }
    }

    Choosing a submission mode

    This template does not support . Every push replaces the contents of the data source, and incremental_change must be false or omitted.

    Sample payloads

    Server mode: a Windows file server with two shares

    This example submits a server and two mounts, with permissions granted to Active Directory groups and a user. Active Directory groups are matched by distinguished name, so the keys for groups are distinguished names rather than display names.

    Folder mode: folders within one share

    This example submits folders for the finance-share mount created above. The root folder carries explicit permissions and its children inherit them.

    Reports inherits the FinanceAdmins group's Full Control binding from finance-root. Payroll declares its own bindings, so nothing is inherited into it.

    Real-world example: Google Drive

    The Veza Google Drive integration models a Google Workspace account as a file system. It submits the Workspace account as a server, each shared drive as a mount, and the folders within each shared drive through separate data sources.

    Google Drive roles map directly onto the permission catalog. Drive exposes five roles that grant access to a shared drive or folder, and each becomes one permission entry with the permission types that role confers. Sharing settings that are not tied to a specific identity, such as "anyone with the link", cannot be expressed as an identity binding, so the integration records them as custom properties on the mount or folder instead.

    Key patterns from this integration:

    • The Workspace customer ID is the server. One server represents the whole account, and every shared drive attaches to it as a mount.

    Top-level payload

    PushTime and TagsDeleteRequests use those exact capitalized keys. Every other field in this template uses lowercase with underscores.

    Server

    Server properties

    Mounts

    Mount properties

    Folders

    Folder properties

    How permission inheritance works

    Permissions

    Permission properties

    Granting permissions

    Custom property definitions

    Creating and updating a file system

    OAA Operations

    API calls for managing and updating custom data sources

    Use these REST API calls to manage and update custom providers and data sources with Open Authorization API.

    Create OAA Custom Provider

    Creates a custom provider for pushing OAA payloads, and returns the provider ID. Set custom_template (or custom_templates) to the OAA template the provider will use, such as application, identity_provider, or hris. See Using the Push API for template options and example requests.

    This endpoint is shared with Create CSV Upload Custom Provider below, so the request schema in the reference includes fields for both workflows. For an OAA push provider, use only the following fields:

    Field
    Type
    Required
    Description

    * Set one of custom_template or custom_templates.

    Creates a custom provider configured for integrations, and returns the provider ID.

    Typically, you will create and configure a CSV integration with the Add Integration flow in the Veza web interface, which builds the mapping configuration for you rather than requiring you to construct it directly. If you build the request yourself, this endpoint is shared with above, so the request schema in the reference includes fields for both workflows. For a CSV Upload provider, use only the following fields:

    Field
    Type
    Required
    Description

    Lists all configured custom providers.

    Returns details for an individual custom provider.

    Update a custom provider.

    Delete a custom provider by ID.

    Return all data sources for a Custom Provider ID.

    You can constrain large responses by adding a filter to the request query string. Include the operator (eq), and value, for example:

    CURL <VEZA_URL>/api/v1/providers/custom?filter=name eq "GitHub"&order_by=state

    Register a new datasource for a custom provider. There can be more than one datasource for a single provider.

    Returns details for a single datasource.

    Unbind a datasource from a custom provider, and delete it.

    To push authorization metadata for a custom datasource, you can specify the source and provider IDs, and upload a payload with the entities and permissions in JSON format.

    A warning is returned for any non-critical errors during payload processing. These can indicate incomplete or inaccurate data in the payload that do not prevent processing, but may warrant attention.

    For large payloads that exceed 100 MB, use the multipart upload endpoint to upload the payload in chunks. See for details, examples, and Python SDK usage.

    For , this endpoint pushes CSV data to an existing datasource. Typically, you will first create the integration and define column mappings using the "Add Integration" flow in Veza.

    CSV data must base64 encoded into the JSON body of the request.

    The populated template can be compressed and encoded, for significantly reduced payload size.

    • Specify the compression_type. Currently supported: GZIP.

    • If compression is selected, Veza will expect the payload json_data as a compressed, base64-encoded string.

    To compress using shell commands:

    Size is typically not an issue when updating custom datasources. However, you may want to compress large payloads. The maximum body size is 100MB (compressed or uncompressed).

    Veza expects the populated template as a single JSON string, enclosed in the request body json_data field. Any "s and non-ASCII characters must be escaped.

    To convert a template to JSON string using Python, the json.dumps() method could be used:

    You can optionally add an icon for your custom provider by uploading a PNG or SVG file (less than 64kb) as a base64-encoded string:

    Upload a custom icon to display for an OAA provider.

    Return the type and string-encoded icon for a custom provider.

    Delete the icon associated with an OAA provider.

    C# OAA Application Connector

    This document provides a high-level overview of and examples for getting started with a new OAA connector to integrate Veza with SaaS applications, infrastructure systems, custom-built applications, and other systems. These examples use C# and the Veza.OAA SDK.

    When developing a connector, source system specifics and individual customer requirements will require alterations to code flow. However, the overall goals, best practices, and development flow are common to most integrations.

    The example code was written with the following goals in mind:

    • Connector should be easy to run from automation platforms and the Command Prompt.

    • Parameters are passed through environment variables as well as command line flags.

    Audit Logs enabled
    When enrichment runs

    Roles become permissions, not entities. Drive has no local users or groups, so the permission catalog carries the role names and identities are referenced by email address.

  • Identities are Google email addresses for both users and groups, matched against the Google Workspace integration through identity_provider_types.

  • Link sharing becomes a property. A "anyone with the link" grant has no identity to bind, so it is recorded in shared_anyone and anyone_role where it remains visible and reportable.

  • Folders arrive on separate data sources and join their shared drive by setting parent_id to the drive ID.

  • mounts

    array

    Array of mount objects. Server mode only, and required when server is sent

    folders

    array

    Array of folder objects. Folder mode only

    permissions

    array

    Array of permission objects. The catalog referenced by every binding

    custom_property_definition

    object

    Defines custom properties for servers, mounts, folders, and permissions. See Custom property definitions

    identity_provider_types

    array

    Restricts which kinds of identity provider are searched when resolving identities. When absent or empty, all of them are searched

    incremental_change

    boolean

    Must be false or omitted. This template does not support incremental updates

    PushTime

    string

    Optional timestamp. Veza overwrites any value you send with the time the push was received

    TagsDeleteRequests

    array

    Optional tag removal requests, each with node_id, type, and tags

    custom_properties

    dictionary

    Custom properties validated against server_properties

    tags

    array

    Specify tags with a key and optional value

    created_at

    string

    RFC3339 timestamp for when the mount was created (optional)

    updated_at

    string

    RFC3339 timestamp for when the mount was last modified (optional)

    identity_to_permissions

    dictionary

    Maps an identity to a list of permission names from the catalog. See Granting permissions

    custom_properties

    dictionary

    Custom properties validated against mount_properties

    tags

    array

    Specify tags with a key and optional value

    path

    string

    Full path to the folder. Veza derives a display name from it using conventions for the declared file_system_type

    parent_id

    string

    The unique_id of the containing folder, or of the mount this folder sits directly beneath

    inherit_parent_permissions

    boolean

    When true and identity_to_permissions is empty, Veza copies the parent folder's bindings onto this folder

    created_at

    string

    RFC3339 timestamp for when the folder was created (optional)

    updated_at

    string

    RFC3339 timestamp for when the folder was last modified (optional)

    identity_to_permissions

    dictionary

    Maps an identity to a list of permission names from the catalog

    custom_properties

    dictionary

    Custom properties validated against folder_properties

    tags

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    Custom properties validated against permission_properties

    tags

    array

    Specify tags with a key and optional value

    google_workspace

    Email address or identity provider ID

    Name or email address

    one_login

    Identity provider ID or email address

    Not matched

    custom

    Identity provider ID or email address

    Identity provider ID only

    server
    incremental updates

    Connector does not require maintenance of state:

    • Connector does not require any persistent data between invocations.

    • There is no special invocation for the first execution.

    • The connector handles all provider and data source management logic.

    • Data source name is unique to the discovered environment.

    The exact flow of an OAA connector can change to meet specific requirements, but the general steps are as follows:

    1. Process and validate configuration parameters. Ensure that all required values are present and valid.

    2. Initialize the API client connection to the Veza tenant. Doing so early in the application flow validates the URL and API key before continuing discovery.

    3. Create an instance of the Veza.OAA.Application.CustomApplication class to populate with application metadata.

    4. Connect to the system and perform discovery of required entities.

      • In your custom integrations, discovery order for users, groups, roles, and other entities can adapt to suit application requirements.

      • Populate the CustomApplication instance with the identity, role, permission, resource, and authorization information collected.

    5. Check if the Provider and Data Source exist on Veza. Create them if they do not exist.

    6. Push the application to the Data Source on Veza. The SDK creates the required JSON payload from the CustomApplication instance.

      • Process any returned warnings or errors.

    7. Exit.

    To use this example as a starting point for your application integration, follow these steps:

    1. Update the name, applicationType, and description of the CustomApplication object based on the source system for integration with Veza.

    2. Define any custom_properties needed. Properties must be defined on the CustomApplication object before their values are set on any entities.

    3. Implement the discovery steps in the Discover() function to collect user, group, role, resource, and permission data for the application. As entities are collected, add them to the CustomApplication object.

    4. Run the connector to validate the output in Veza.

    The following code provides a template and examples for creating a new application integration using the Veza.OAA SDK.

    Code goals

    High-level code flow

    Customizing the example

    Example: custom application

    {
      "file_system_type": "Windows File Server",
      "identity_provider_types": ["active_directory"],
      "custom_property_definition": {
        "server_properties": {
          "datacenter": "STRING"
        },
        "mount_properties": {
          "quota_gb": "NUMBER",
          "encrypted": "BOOLEAN"
        },
        "permission_properties": {},
        "folder_properties": {}
      },
      "permissions": [
        {
          "name": "Full Control",
          "description": "Read, write, and change permissions",
          "permission_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"]
        },
        {
          "name": "Read",
          "description": "Read files and list contents",
          "permission_type": ["DataRead", "MetadataRead"]
        }
      ],
      "server": {
        "unique_id": "fs-prod-01",
        "name": "fs-prod-01.example.com",
        "description": "Primary file server",
        "custom_properties": {
          "datacenter": "iad1"
        },
        "tags": [
          {
            "key": "environment",
            "value": "production"
          }
        ]
      },
      "mounts": [
        {
          "unique_id": "finance-share",
          "name": "Finance",
          "description": "Finance department share",
          "created_at": "2025-03-14T00:00:00Z",
          "identity_to_permissions": {
            "CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"],
            "alice@example.com": ["Read"]
          },
          "custom_properties": {
            "quota_gb": 500,
            "encrypted": true
          }
        },
        {
          "unique_id": "public-share",
          "name": "Public",
          "identity_to_permissions": {
            "CN=Domain Users,CN=Users,DC=example,DC=com": ["Read"]
          }
        }
      ]
    }
    {
      "file_system_type": "Windows File Server",
      "server_unique_id": "fs-prod-01",
      "permissions": [
        {
          "name": "Full Control",
          "description": "Read, write, and change permissions",
          "permission_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"]
        },
        {
          "name": "Read",
          "description": "Read files and list contents",
          "permission_type": ["DataRead", "MetadataRead"]
        }
      ],
      "folders": [
        {
          "unique_id": "finance-root",
          "name": "Finance",
          "path": "\\\\fs-prod-01\\Finance",
          "parent_id": "finance-share",
          "inherit_parent_permissions": false,
          "identity_to_permissions": {
            "CN=FinanceAdmins,OU=Groups,DC=example,DC=com": ["Full Control"]
          }
        },
        {
          "unique_id": "finance-reports",
          "name": "Reports",
          "path": "\\\\fs-prod-01\\Finance\\Reports",
          "parent_id": "finance-root",
          "inherit_parent_permissions": true
        },
        {
          "unique_id": "finance-payroll",
          "name": "Payroll",
          "path": "\\\\fs-prod-01\\Finance\\Payroll",
          "parent_id": "finance-root",
          "inherit_parent_permissions": false,
          "identity_to_permissions": {
            "CN=PayrollTeam,OU=Groups,DC=example,DC=com": ["Full Control"]
          }
        }
      ]
    }
    {
      "file_system_type": "Google Drive",
      "identity_provider_types": ["google_workspace"],
      "custom_property_definition": {
        "mount_properties": {
          "admin_managed_restrictions": "BOOLEAN",
          "domain_users_only": "BOOLEAN",
          "drive_members_only": "BOOLEAN",
          "shared_anyone": "BOOLEAN",
          "anyone_role": "STRING",
          "shared_domain": "BOOLEAN",
          "domain_role": "STRING"
        },
        "folder_properties": {
          "shared_anyone": "BOOLEAN",
          "anyone_role": "STRING",
          "shared_domain": "BOOLEAN",
          "domain_role": "STRING"
        }
      },
      "permissions": [
        {
          "name": "organizer",
          "description": "Manage members, content, and settings",
          "permission_type": ["DataRead", "DataWrite", "MetadataRead", "MetadataWrite", "DataCreate", "DataDelete"]
        },
        {
          "name": "fileOrganizer",
          "description": "Manage content but not members",
          "permission_type": ["DataRead", "DataWrite", "MetadataRead", "MetadataWrite", "DataCreate", "DataDelete"]
        },
        {
          "name": "writer",
          "description": "Add and edit content",
          "permission_type": ["DataRead", "DataWrite", "MetadataRead", "MetadataWrite", "DataCreate", "DataDelete"]
        },
        {
          "name": "commenter",
          "description": "Comment on content",
          "permission_type": ["DataRead", "MetadataRead", "MetadataWrite"]
        },
        {
          "name": "reader",
          "description": "View content",
          "permission_type": ["DataRead", "MetadataRead"]
        }
      ],
      "server": {
        "unique_id": "C01abc234",
        "name": "C01abc234"
      },
      "mounts": [
        {
          "unique_id": "0ABcDeFgHiJkLmNoPQ",
          "name": "Engineering",
          "created_at": "2024-06-01T12:00:00Z",
          "identity_to_permissions": {
            "alice@example.com": ["organizer"],
            "engineering@example.com": ["writer"]
          },
          "custom_properties": {
            "admin_managed_restrictions": true,
            "domain_users_only": false,
            "drive_members_only": true,
            "shared_anyone": false,
            "shared_domain": false
          }
        }
      ]
    }
    example_app.cs
    using RestSharp;
    using RestSharp.Authenticators;
    using Veza.OAA;
    using Veza.OAA.Application;
    using Veza.OAA.Client;
    using NLog;
    
    namespace Example.Integrations
    {
        /// <summary>
        /// Example application group object
        /// </summary>
        public class AppGroup {
            public string Name { get; set; }
            public string Type { get; set; }
            public string CreatedAt { get; set; }
            public List<string> Users { get; set; }
        }
    
        /// <summary>
        /// Example application resource object
        /// </summary>
        public class AppResource {
            public string Name { get; set; }
            public int SiteId { get; set; }
            public string ResourceType { get; set; }
        }
    
        /// <summary>
        /// Example application role object
        /// </summary>
        public class AppRole {
            public string Name { get; set; }
            public int SystemId { get; set; }
            public string CreatedAt { get; set; }
            public List<string> Users { get; set; }
            public List<string> Resources { get; set; }
        }
    
        public class ExampleApp
        {
            // Optional NLog logger; can be replaced with any standard logging interface
            private static Logger logger = LogManager.GetCurrentClassLogger();
    
            // The base64-encoded logo for the application (displayed on the Veza UI)
            public string LogoBase64;
    
            // The name of the provider for the application
            public string ProviderName;
    
            // The custom application object for the example application
            // This object is used to build the application payload for Veza
            public CustomApplication CustomApp { get; set; }
    
            // The example application client for the example application API (not shown in this example)
            private ExampleAppClient AppClient { get; set; }
    
            # region "Construction"
            public ExampleApp()
            {
                // Instantiate the example application
                CustomApp = new CustomApplication(
                    name: "Example Application 1",
                    applicationType: "Example App",
                    description: "Example application for Veza integration"
                );
    
                // Define an "uncategorized" permission for the example application
                // This can be used to group permissions that do not fit into another category,
                // or if the application API does not provide permission information
                CustomApp.AddCustomPermission(
                    name: "Uncategorized",
                    permissions: new List<Permission> { Permission.Uncategorized }
                );
    
                // define custom properties for the example application
                DefineCustomProperties();
    
                // Set the application icon for the Veza UI
                // This should be a base64-encoded SVG or PNG image
                LogoBase64 = "abc123...def987654"
            }
    
            /// <summary>
            /// Define custom properties for the example application.
            /// This method is called by the constructor to define any custom properties
            /// that the example application entities may have.
            /// </summary>
            private void DefineCustomProperties()
            {
                CustomApp.DefinedProperties[typeof(User)].
                    DefineProperty("locked_out", typeof(bool);
                CustomApp.DefinedProperties[typeof(Group)].
                    DefineProperty("type", typeof(string));
                CustomApp.DefinedProperties[typeof(Role)].
                    DefineProperty("system_id", typeof(int));
                CustomApp.DefineResourceProperty("site_id", typeof(int)), "widget");
            }
    
            # endregion
    
            # region "Discovery"
            // Individual methods for discovering users, groups, roles, and resources.
            // Should be scoped as private to ensure that they are called only by the Discover method
            // and not directly by the client application.
    
            /// <summary>
            /// Discover users for the example application.
            /// This method is called by the Discover method to discover users for the example application.
            /// </summary>
            private void DiscoverUsers()
            {
                Logger.Info("Discovering users for the example application");
    
                // Get users from the example application client.
                // In this example, the GetUsers method returns a list of dictionaries of user data.
                List<Dictionary<string, string>> users = AppClient.GetUsers();
    
                // Iterate over the users response and add them to the application payload
                foreach (Dictionary<string, string> u in users)
                {
                    // Create a new user object and add it to the application payload
                    User user = CustomApp.AddUser(name: u["username"]);
                    user.AddIdentity(u["email"]);
                    user.IsActive = u["active"];
                    user.CreatedAt = u["created_at"];
                }
    
                Logger.Info("User discovery complete");
            }
    
            /// <summary>
            /// Discover groups for the example application.
            /// This method is called by the Discover method to discover groups for the example application.
            /// </summary>
            private void DiscoverGroups()
            {
                Logger.Info("Discovering groups for the example application");
    
                // Get groups from the example application client
                // in this example, the GetGroups method returns a list of AppGroup objects
                List<AppGroup> groups = AppClient.GetGroups();
    
                // Iterate over the groups response and add them to the application payload
                foreach (AppGroup g in groups)
                {
                    // Create a new group object and add it to the application payload
                    Group group = CustomApp.AddGroup(name: g.Name);
                    group.CreatedAt = g.CreatedAt;
                    group.SetProperty(name: "type", value: g.Type);
    
                    // Iterate users in the group and add them to the group
                    foreach (string user in g.Users)
                    {
                        CustomApp.Users[user].AddGroup(g.Name);
                    }
                }
    
                Logger.Info("Group discovery complete");
            }
    
            /// <summary>
            /// Discover resources for the example application.
            /// This method is called by the Discover method to discover resources for the example application.
            /// </summary>
            private void DiscoverResources()
            {
                Logger.Info("Discovering resources for the example application");
    
                // Get resources from the example application
                // In this example, the GetResources method returns a list of AppResource objects
                List<AppResource> resources = AppClient.GetResources();
                foreach (AppResource r in resources)
                {
                    // Create a resource object and add it to the application payload
                    Resource resource = CustomApp.AddResource(name: r.Name, resourceType: r.ResourceType);
    
                    // Set the `site_id` property for the resource if the resource is a "widget"
                    // Cstom resource properties are defined per-resource type, so non-"widget" resources will not have this property
                    if (r.ResourceType == "widget")
                    {
                        resource.SetProperty(name: "site_id", value: r.SiteId);
                    }
                }
    
                Logger.Info("Resource discovery complete");
            }
    
            /// <summary>
            /// Discover roles for the example application.
            /// This method is called by the Discover method to discover roles for the example application.
            /// </summary>
            private void DiscoverRoles()
            {
                Logger.Info("Discovering roles for the example application");
    
                // get roles from the example application
                // in this example, the GetRoles method returns a list of AppRole objects
                List<AppRole> roles = AppClient.GetRoles();
                foreach (Role role in roles)
                {
                    // create a new role object and add it to the application payload
                    Role role = CustomApp.AddRole(name: role.Name);
                    role.CreatedAt = role.CreatedAt;
                    role.SetProperty(name: "system_id", value: role.SystemId);
    
                    // iterate users in the role and add them to the role
                    // set the applyToApplication flag to true to apply the role to the entire application
                    foreach (string user in role.Users)
                    {
                        CustomApp.Users[user].AddRole(name: role.Name, applyToApplication: true);
                    }
                    Application.AddRole(role);
                }
    
                Logger.Info("Role discovery complete");
            }
    
            # endregion
    
            # region "Execution"
    
            /// <summary>
            /// Discover the example application.
            /// This method is called by the Run method to discover the example application.
            /// It serves as a place to instantiate a client for the example application API
            /// and then call each of the discovery methods required to build the application payload.
            /// </summary>
            /// <param name="exampleApiKey">The API key for the example application API</param>
            /// <param name="exampleUrl">The URL for the example application API</param>
            /// <returns></returns>
            public void Discover(string exampleApiKey, string exampleUrl)
            {
                // instantiate an API client for the example application
                AppClient = new ExampleAppClient(exampleApiKey, exampleUrl);
    
                Logger.Info("Beginning example application discovery");
    
                // discover the example application components
                DiscoverUsers();
                DiscoverGroups();
                DiscoverResources();
                DiscoverRoles();
    
                Logger.Info("Example application discovery complete");
            }
    
            /// <summary>
            /// Handle integration execution.
            /// This is separated from the Main method to more easily adapt to changes
            /// to application execution (e.g. from Command Prompt, as part of another application, etc.)
            /// </summary>
            /// <param name="exampleApiKey">The API key for the Example application API</param>
            /// <param name="exampleUrl">The URL for the Example application API</param>
            /// <param name="vezaApiKey">The API key for the Veza tenant</param>
            /// <param name="vezaUrl">The URL for the Veza tenant</param>
            /// <returns></returns>
            public async Task Run(
                string exampleApiKey,
                string exampleUrl,
                string vezaApiKey,
                string vezaUrl
            )
            {
                Logger.Info("Starting example application discovery");
    
                // Instantiate a connection to the Veza API.
                // The client will attempt to reach the Veza API and throw an exception if it fails.
                // This is to ensure that the Veza API is reachable before attempting to discover and push data.
                try
                {
                    OAAClient oaaClient = new(vezaApiKey, vezaUrl);
                }
                catch (ClientException e)
                {
                    Logger.Error("Failed to connect to Veza API: {0}", e.Message);
                    return;
                }
    
                // Discover the example application
                Discover(exampleApiKey, exampleUrl);
    
                // Get or create the Veza provider for the payload
                Logger.Debug("Checking Veza for an existing provider for the example application");
                Sdk.Client.ApiClient.VezaApiResponse providerResponse = await oaaClient.GetProvider(ProviderName);
    
                // Create the provider if none exists
                if (providerResponse is null)
                {
                    Logger.Info("No Veza provider exists; creating provider");
                    await oaaClient.CreateProvider(ProviderName, "application", base64_icon: LogoBase64);
                }
    
                // Push OAA payload to Veza
                Logger.Info("Pushing example application metadata to Veza");
                RestResponse<Sdk.Client.ApiClient.VezaApiResponse> pushResponse = await oaaClient.PushApplication(ProviderName, Environment.MachineName, CustomApp, save_json: true);
                if (pushResponse.IsSuccessful)
                {
                    Logger.Info("Example application discovery complete");
                } else
                {
                    Logger.Error($"Push response code: {pushResponse.StatusCode}");
                    Logger.Error($"Push response content: {pushResponse.Content}");
                }
            }
    
            # endregion
        }
    }

    provisioning

    boolean

    No

    Set to true to use the provider with Lifecycle Management: as a source of identity with the hris or identity_provider template, or as a provisioning target with external_lifecycle_management_type.

    external_lifecycle_management_type

    string

    No

    How Lifecycle Management provisions to the application: SCIM, SEND_REST_PAYLOAD, SEND_XML_PAYLOAD, or SEND_SQL_COMMAND. Requires provisioning set to true.

    configuration_json

    string

    With SCIM

    JSON-encoded SCIM connection details. See . Leave empty otherwise.

    data_plane_id

    string

    With SEND_REST_PAYLOAD, SEND_XML_PAYLOAD, or SEND_SQL_COMMAND

    ID of the Insight Point that sends the requests. See . Leave empty when external_lifecycle_management_type is not set.

    notification_preferences

    object

    No

    Configure notifications for this provider.

    array

    No

    A list with the template named in csv_mapping_configuration.template_type, for example ["secret_scanner"]. A CSV integration created in Veza sets it the same way.

    csv_mapping_configuration

    object

    Yes

    The template in template_type (application, hris, secret_store, or secret_scanner) and the column mappings. See , and for the Secret Scanner template, .

    provisioning

    boolean

    No

    For the HRIS template, this is derived from csv_mapping_configuration.hris.hris_provisioning_source rather than set directly.

    notification_preferences

    object

    No

    Configure notifications for file upload and extraction status. See .

    name

    string

    Yes

    Provider name.

    custom_template

    string

    Yes*

    OAA template type, such as application, identity_provider, hris, principal, or secret_store.

    custom_templates

    array

    Yes*

    Use instead of custom_template to combine multiple templates on one provider, for example principal and application.

    name

    string

    Yes

    Provider name.

    push_type

    string

    Yes

    Set to CSV.

    POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:parts
    {
        "csv_data": "abc123="
    }
    CSV_PAYLOAD=$(cat my_app_data.csv | base64)
    curl --location https://example.vezacloud.com/api/v1/providers/custom/40bdd318-d320-4574-be90-ca556d59889a/datasources/9bc29dc6-8cd0-4926-992e-7d720305ae2f:push_csv \
    --request POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $VEZA_API_KEY" \
    --data "{\"csv_data\": \"${CSV_PAYLOAD}\"}"
    cat app_payload.json | gzip | base64 -o json_data.b64
    payload = {"id": provider_id,
               "data_source_id": data_source_id,
               "json_data": json.dumps(template_contents)
               }
    curl -X POST '{{VezaURL}}/api/v1/providers/custom/962d5eff-285c-4b08-a54e-400eead1e680:icon' \
    -H "authorization: Bearer $API_KEY" \
    -d '{"icon_base64": "PHN2ZyBmaWxsPSIjMDAwMDAwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciICB2aWV3Qm94PSIwIDAgNjQgNjQiIHdpZHRoPSIzMnB4IiBoZWlnaHQ9IjMycHgiPjxwYXRoIGQ9Ik0zMiA2QzE3LjY0MSA2IDYgMTcuNjQxIDYgMzJjMCAxMi4yNzcgOC41MTIgMjIuNTYgMTkuOTU1IDI1LjI4Ni0uNTkyLS4xNDEtMS4xNzktLjI5OS0xLjc1NS0uNDc5VjUwLjg1YzAgMC0uOTc1LjMyNS0yLjI3NS4zMjUtMy42MzcgMC01LjE0OC0zLjI0NS01LjUyNS00Ljg3NS0uMjI5LS45OTMtLjgyNy0xLjkzNC0xLjQ2OS0yLjUwOS0uNzY3LS42ODQtMS4xMjYtLjY4Ni0xLjEzMS0uOTItLjAxLS40OTEuNjU4LS40NzEuOTc1LS40NzEgMS42MjUgMCAyLjg1NyAxLjcyOSAzLjQyOSAyLjYyMyAxLjQxNyAyLjIwNyAyLjkzOCAyLjU3NyAzLjcyMSAyLjU3Ny45NzUgMCAxLjgxNy0uMTQ2IDIuMzk3LS40MjYuMjY4LTEuODg4IDEuMTA4LTMuNTcgMi40NzgtNC43NzQtNi4wOTctMS4yMTktMTAuNC00LjcxNi0xMC40LTEwLjQgMC0yLjkyOCAxLjE3NS01LjYxOSAzLjEzMy03Ljc5MkMxOS4zMzMgMjMuNjQxIDE5IDIyLjQ5NCAxOSAyMC42MjVjMC0xLjIzNS4wODYtMi43NTEuNjUtNC4yMjUgMCAwIDMuNzA4LjAyNiA3LjIwNSAzLjMzOEMyOC40NjkgMTkuMjY4IDMwLjE5NiAxOSAzMiAxOXMzLjUzMS4yNjggNS4xNDUuNzM4YzMuNDk3LTMuMzEyIDcuMjA1LTMuMzM4IDcuMjA1LTMuMzM4LjU2NyAxLjQ3NC42NSAyLjk5LjY1IDQuMjI1IDAgMi4wMTUtLjI2OCAzLjE5LS40MzIgMy42OTdDNDYuNDY2IDI2LjQ3NSA0Ny42IDI5LjEyNCA0Ny42IDMyYzAgNS42ODQtNC4zMDMgOS4xODEtMTAuNCAxMC40IDEuNjI4IDEuNDMgMi42IDMuNTEzIDIuNiA1Ljg1djguNTU3Yy0uNTc2LjE4MS0xLjE2Mi4zMzgtMS43NTUuNDc5QzQ5LjQ4OCA1NC41NiA1OCA0NC4yNzcgNTggMzIgNTggMTcuNjQxIDQ2LjM1OSA2IDMyIDZ6TTMzLjgxMyA1Ny45M0MzMy4yMTQgNTcuOTcyIDMyLjYxIDU4IDMyIDU4IDMyLjYxIDU4IDMzLjIxMyA1Ny45NzEgMzMuODEzIDU3Ljkzek0zNy43ODYgNTcuMzQ2Yy0xLjE2NC4yNjUtMi4zNTcuNDUxLTMuNTc1LjU1NEMzNS40MjkgNTcuNzk3IDM2LjYyMiA1Ny42MSAzNy43ODYgNTcuMzQ2ek0zMiA1OGMtLjYxIDAtMS4yMTQtLjAyOC0xLjgxMy0uMDdDMzAuNzg3IDU3Ljk3MSAzMS4zOSA1OCAzMiA1OHpNMjkuNzg4IDU3LjljLTEuMjE3LS4xMDMtMi40MTEtLjI4OS0zLjU3NC0uNTU0QzI3LjM3OCA1Ny42MSAyOC41NzEgNTcuNzk3IDI5Ljc4OCA1Ny45eiIvPjwvc3ZnPg=="}'

    Create CSV Upload Custom Provider

    List Custom Providers

    Get Custom Provider by ID

    Update Custom Provider

    Delete Custom Provider

    List Custom Provider Datasources

    Veza expects that spaces in URLS are encoded as "+" (for example?name+eq+"GitHub"&order_by=state). Note that some libraries and clients will encode spaces as "%2B" by default, which will cause errors unless you override this behavior.

    Create Custom Provider Datasource

    Get Datasource by ID

    Delete Custom Provider Datasource

    You can also delete OAA datasources from the Veza web interface. On the Integrations page, find the OAA datasource in the list and click the action menu (⋮) to access the Delete option.

    Push Custom Provider Datasource

    Multipart Push Custom Provider Datasource

    Push Custom Provider Datasource CSV

    Compression

    Escaping unsafe characters

    Custom Provider Icons

    Create Custom Provider Icon

    Get Custom Provider Icon

    Delete Custom Provider Icon

    CSV Upload
    Create OAA Custom Provider
    Multipart Upload
    CSV Upload Integrations

    custom_templates

    Secret Store

    Classes for constructing an OAA JSON payload for Secret Store

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • PROPERTY_NAME_REGEX


    class SecretStoreSubmission

    Class for modeling Secret Store Template

    SecretStore template consists of base information about the secret store instance, permissions, vaults, entries, and identity mappings.

    Args:

    • name (str): Name for Secret Store Instance

    • secret_store_type (str): Type for Secret Store. Typically the vendor or product name.

    • unique_id (str): Unique identify for secret store instance. Optional, defaults to name.

    • skip_local_users_creation (bool, optional): Skip creation of local user identities for this secret store. Defaults to None.

    Attributes:

    • secret_store (SecretStore): The secret store entity

    • property_definitions (SecretStorePropertyDefinitions): Custom property definitions

    • identity_mapping_configuration (IdentityMappingConfigurationSubmission): Identity mapping configuration, set via set_identity_mapping_configuration().


    Get the OAA payload.

    Returns the complete OAA template payload for Secret Store as serializable dictionary

    Returns:

    • dict: OAA payload as dictionary

    Raises:

    • OAATemplateException: If secret_store is not set


    Create and set the identity mapping configuration.

    Initializes the identity_mapping_configuration attribute with a new IdentityMappingConfigurationSubmission instance and returns it for further configuration.

    Returns:

    • IdentityMappingConfigurationSubmission: The identity mapping configuration.


    Secret Store Entity

    Represents a secret store application with permissions, vaults, and identity mappings.

    Args:

    • name (str): Display name for secret store

    • unique_id (str, optional): Unique identifier for secret store

    • description (str, optional): Description of the secret store


    Add identity to permission mapping

    Args:

    • identity (str): The identity ID

    • identity_type (str): The type of identity (e.g., "local_user")

    • permission_assignments (list[PermissionAssignment], optional): Permission assignments for this identity

    Returns:

    • IdentityToPermission: The identity to permission mapping

    Raises:

    • OAATemplateException: Identity to permission mapping for identity and identity_type already exists


    Add a new Permission

    Args:

    • name (str): Display name for permission

    • unique_id (str, optional): Unique identifier for permission. Defaults to name if not provided.

    • resource (str, optional): Resource this permission applies to

    Returns:

    • SecretStorePermission: Entity for new permission

    Raises:

    • OAATemplateException: Permission with ID already exists


    Add a new tag to secret store.

    Args:

    • key (str): Tag key/name

    • value (str, optional): Tag value. Defaults to "".


    Add a new Vault

    Args:

    • name (str): Display name for vault

    • vault_type (str): Type of vault (user-defined)

    • unique_id (str, optional): Unique identifier for vault. Defaults to name if not provided.

    Returns:

    • SecretStoreVault: Entity for new vault

    Raises:

    • OAATemplateException: Vault with ID already exists


    Set secret store custom property value

    Property name must be defined before calling set_property

    Args:

    • property_name (str): Name of property

    • property_value (any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Return the dictionary representation of secret store.


    Secret Store Permission Entity

    Represents a permission in a secret store.

    Args:

    • name (str): Display name for permission

    • unique_id (str, optional): Unique identifier for permission

    • resource (str, optional): Resource this permission applies to

    Attributes:

    • permission_type (list[OAAPermission]): List of OAAPermission enums that represent the canonical permissions


    Add a permission type to the permission_type list.

    Extends the list of canonical OAAPermission types this permission grants.

    Args:

    • permission_type (OAAPermission): The OAAPermission enum value to add

    Raises:

    • OAATemplateException: If permission_type is not an OAAPermission enum


    Add a new tag to permission.

    Args:

    • key (str): Tag key/name

    • value (str, optional): Tag value. Defaults to "".


    Set permission custom property value

    Property name must be defined before calling set_property

    Args:

    • property_name (str): Name of property

    • property_value (any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Return the dictionary representation of permission.


    Secret Store Vault Entity

    Represents a vault in a secret store.

    Args:

    • name (str): Display name for vault

    • vault_type (str): Type of vault (user-defined)

    • unique_id (str, optional): Unique identifier for vault


    Add a new Entry to vault

    Args:

    • name (str): Display name for entry

    • unique_id (str, optional): Unique identifier for entry. Defaults to name if not provided.

    • description (str, optional): Description of the entry

    Returns:

    • SecretStoreVaultEntry: Entity for new entry

    Raises:

    • OAATemplateException: Entry with ID already exists


    Add a new tag to vault.

    Args:

    • key (str): Tag key/name

    • value (str, optional): Tag value. Defaults to "".


    Set vault custom property value

    Property name must be defined before calling set_property

    Args:

    • property_name (str): Name of property

    • property_value (any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Return the dictionary representation of vault.


    Secret Store Vault Entry Entity

    Represents an entry (credential) in a vault.

    Args:

    • name (str): Display name for entry

    • unique_id (str, optional): Unique identifier for entry

    • description (str, optional): Description of the entry


    Add an identity to this vault entry

    Args:

    • identity_type (str): The type of identity (e.g., "OktaUser", "AzureADUser")

    • external_id (str): The external ID of the identity

    Returns:

    • VaultEntryIdentity: The identity entity


    Add a new tag to entry.

    Args:

    • key (str): Tag key/name

    • value (str, optional): Tag value. Defaults to "".


    Set entry custom property value

    Property name must be defined before calling set_property

    Args:

    • property_name (str): Name of property

    • property_value (any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Return the dictionary representation of entry.


    Vault Entry Identity

    Represents identity information for a vault entry.

    Args:

    • identity_type (str): The type of identity (e.g., "OktaUser", "AzureADUser")

    • external_id (str): The external ID of the identity


    Return the dictionary representation of identity.


    Identity to Permission Mapping

    Maps an identity to permissions on vaults.

    Args:

    • identity (str): The identity ID

    • identity_type (str): The type of identity (e.g., "local_user")

    • permission_assignments (list[PermissionAssignment], optional): Permission assignments for this identity


    Add a permission assignment

    Args:

    • vault (list[str]): List of vault IDs or names

    • permissions (list[str]): List of permission names

    Returns:

    • PermissionAssignment: The permission assignment


    Return the dictionary representation of identity to permission.


    Permission Assignment

    Assigns permissions to vaults.

    Args:

    • vault (list[str]): List of vault IDs or names

    • permissions (list[str]): List of permission names


    Return the dictionary representation of permission assignment.


    Property Definitions for Secret Store entities


    Define a custom property for entries

    Args:

    • name (str): Property name

    • property_type (OAAPropertyType): Property type


    Define a custom property for permissions

    Args:

    • name (str): Property name

    • property_type (OAAPropertyType): Property type


    Define a custom property for secret store

    Args:

    • name (str): Property name

    • property_type (OAAPropertyType): Property type


    Define a custom property for vaults

    Args:

    • name (str): Property name

    • property_type (OAAPropertyType): Property type


    Convert property definitions to dictionary


    Check property name for valid characters

    Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.

    Args:

    • name (str): name of property to validate

    Raises:

    • OAATemplateException: Name is not a string

    • OAATemplateException: Name contains invalid characters or does not start with a letter

    CMDB

    Template for modeling configuration management databases with configuration items and owner correlation

    Use this template to model a configuration management database using the . The CMDB template brings asset inventory into Veza as configuration items, and correlates each item to the identity that owns it and to the Veza entity it represents.

    The template models a shallow structure:

    • CMDB instance - the source system, such as a ServiceNow or Freshservice tenant

      • Configuration item - one asset tracked in that system, such as a server, a database, or a laptop

    Only the configuration item becomes an entity in the Authorization Graph. The instance supplies the cmdb_type

    skip_local_users_creation (bool, optional): Skip creation of local user identities for this secret store.

    allow_identity_assume (bool, optional): Whether this permission allows identity assumption
  • permission_type (list[OAAPermission], optional): List of OAAPermission enums that represent the canonical permissions

  • description (str, optional): Description of the vault
    allow_identity_assume (bool, optional): Whether this permission allows identity assumption
  • permission_type (list[OAAPermission], optional): List of OAAPermission enums that represent the canonical permissions

  • description
    (str, optional): Description of the vault

    method __init__

    method get_payload

    method set_identity_mapping_configuration

    class SecretStore

    method __init__

    method add_identity_to_permission

    method add_permission

    method add_tag

    method add_vault

    method set_property

    method to_dict

    class SecretStorePermission

    method __init__

    method add_permission_type

    method add_tag

    method set_property

    method to_dict

    class SecretStoreVault

    method __init__

    method add_entry

    method add_tag

    method set_property

    method to_dict

    class SecretStoreVaultEntry

    method __init__

    method add_identity

    method add_tag

    method set_property

    method to_dict

    class VaultEntryIdentity

    method __init__

    method to_dict

    class IdentityToPermission

    method __init__

    method add_permission_assignment

    method to_dict

    class PermissionAssignment

    method __init__

    method to_dict

    class SecretStorePropertyDefinitions

    method __init__

    method define_entry_property

    method define_permission_property

    method define_secret_store_property

    method define_vault_property

    method to_dict

    method validate_name

    __init__(
        name: 'str',
        secret_store_type: 'str',
        unique_id: 'str' = None,
        skip_local_users_creation: 'Optional[bool]' = None
    )
    get_payload() → dict
    set_identity_mapping_configuration() → IdentityMappingConfigurationSubmission
    __init__(name: 'str', unique_id: 'str' = None, description: 'str' = None)
    add_identity_to_permission(
        identity: 'str',
        identity_type: 'str',
        permission_assignments: 'List[PermissionAssignment]' = None
    ) → IdentityToPermission
    add_permission(
        name: 'str',
        unique_id: 'str' = None,
        resource: 'str' = None,
        allow_identity_assume: 'bool' = None,
        permission_type: 'List[OAAPermission]' = None
    ) → SecretStorePermission
    add_tag(key: 'str', value: 'str' = '') → None
    add_vault(
        name: 'str',
        vault_type: 'str',
        unique_id: 'str' = None,
        description: 'str' = None
    ) → SecretStoreVault
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str' = None,
        resource: 'str' = None,
        allow_identity_assume: 'bool' = None,
        permission_type: 'List[OAAPermission]' = None
    )
    add_permission_type(permission_type: 'OAAPermission') → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        vault_type: 'str',
        unique_id: 'str' = None,
        description: 'str' = None
    )
    add_entry(
        name: 'str',
        unique_id: 'str' = None,
        description: 'str' = None
    ) → SecretStoreVaultEntry
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(name: 'str', unique_id: 'str' = None, description: 'str' = None)
    add_identity(identity_type: 'str', external_id: 'str') → VaultEntryIdentity
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(identity_type: 'str', external_id: 'str')
    to_dict() → dict
    __init__(
        identity: 'str',
        identity_type: 'str',
        permission_assignments: 'List[PermissionAssignment]' = None
    )
    add_permission_assignment(
        vault: 'List[str]',
        permissions: 'List[str]'
    ) → PermissionAssignment
    to_dict() → dict
    __init__(vault: 'List[str]', permissions: 'List[str]')
    to_dict() → dict
    __init__()
    define_entry_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_permission_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_secret_store_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_vault_property(name: 'str', property_type: 'OAAPropertyType') → None
    to_dict() → dict
    validate_name(name: 'str') → None
    that labels each item and groups the custom property definitions.

    A custom property definition can define additional properties for configuration items.

    To use the CMDB template, set the template type to cmdb when creating a new data provider:

    Field
    Type
    Description

    cmdb_instances

    array

    Required. Array of objects

    custom_property_definition

    object

    Declares custom properties per cmdb_type. See

    An instance identifies the source system. It contributes cmdb_type to each of its configuration items and carries the correlation configuration.

    Field
    Type
    Description

    name

    string

    Display name for the instance

    cmdb_type

    string

    The kind of CMDB, for example Freshservice or ServiceNow. Labels every configuration item in the instance and keys the custom property definitions

    configuration_items

    array

    Required. Array of objects

    Veza does not check that name or cmdb_type is present. cmdb_type is a free-form string. Veza records the distinct values a provider has submitted so they can be filtered on, but does not restrict them to a fixed list.

    A configuration item is one tracked asset. It is the only entity this template creates in the Authorization Graph.

    Field
    Type
    Description

    id

    string

    Required. Identifier for the item, unique within its instance

    name

    string

    Display name for the item

    cmdb_asset_type

    string

    The kind of asset, for example Server or Laptop. Used to map the item to a Veza entity type. See

    cmdb_asset_type is a free-form string. Veza does not validate it against a list, and values such as Server, Database, Application, and Laptop are conventions rather than an enumeration. Use whatever your source system calls the asset type.

    What the value does is select how the item is correlated to the rest of the graph. Veza first looks for an entry in assetConnections whose assetTypeValue matches. When none matches, it attempts to infer the target entity type from the name, so common values resolve without configuration. Declaring the mapping explicitly is more reliable than relying on inference.

    Two relationships make a configuration item useful: who owns the asset, and which Veza entity the asset already corresponds to. Both are resolved after the push, from values you supply, and both appear as properties on the configuration item rather than as relationships in the graph.

    Two keys are sent inside custom_properties but are not custom properties. Veza reads them, promotes them to standard properties on the configuration item, and removes them from the custom property map.

    Key
    Description

    owner_external_id

    Identifies the person who owns the asset, typically an email address

    asset_external_id

    Identifies the Veza entity this item describes, typically a resource name

    csc_global_config tells Veza where to look for each match.

    Field
    Type
    Description

    ownerIdColumnName

    string

    The field in the source system that holds the owner identifier

    assetIdColumnName

    string

    The field in the source system that holds the asset identifier

    assetTypeColumnName

    string

    The field in the source system that holds the asset type

    Each entry in assetConnections has three fields:

    Field
    Type
    Description

    assetTypeValue

    string

    The cmdb_asset_type value this entry applies to

    assetNodeType

    string

    The Veza entity type that asset type corresponds to

    assetPropertyName

    string

    The property on that entity type to match asset_external_id against

    assetNodeType must be an entity type that represents a resource, role, identity, or entitlement, written exactly as Veza names it, for example S3Bucket rather than AwsS3Bucket. An entry whose assetNodeType is not a valid entity type is skipped, and the push still succeeds, so a misspelled type falls back to inference without any error.

    Veza matches owner_external_id against the named property on the named entity type, without regard to letter case, and records a match on the configuration item. If several entities share the same value, any one of them can be recorded, so match on a property that is unique. When nothing matches, Veza clears the owner rather than leaving a previous value in place, so a stale correlation cannot persist across pushes.

    The asset side clears the same way when the item's cmdb_asset_type still maps to an entity type but no entity of that type matches asset_external_id. If the asset type no longer maps to any entity type, the previous asset correlation is left in place.

    Neither side clears when its input is removed. Taking owner_external_id or asset_external_id off an item leaves that side's previous correlation in place, and removing csc_global_config leaves the previous owner in place.

    Resolution runs after the payload has been processed, so a correlation can succeed on a later push once the integration owning the matched entity has been added.

    Custom properties allow you to attach additional metadata to configuration items. Definitions are declared per cmdb_type, so one payload can carry definitions for several instances.

    Scope
    Description

    configuration_item_properties

    Custom properties for configuration item entities

    Configuration items are the only entity type in this template, so there is one scope. Property values must match their declared type. Supported types are described in Custom properties.

    Custom properties are processed only when custom_property_definition is present. When it is absent, custom properties are ignored. When it is present, the push itself is accepted without checking custom properties. A property that the definition does not declare, or custom properties sent for a cmdb_type the definition does not cover, causes processing of the whole data source to fail after the push.

    To create the OAA provider and push data:

    1. Create the provider with the cmdb template type:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"MyCMDB","custom_template":"cmdb"}'
    2. Create a data source on the provider:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data '{"name":"my_cmdb_source"}'
    3. Push the payload to the data source:

      curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
      -H "authorization: Bearer {API_KEY}" \
      -H "Content-Type: application/json" \
      --data "{\"json_data\": $(jq -Rs . payload.json)}"

      The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json and escapes it as a JSON string.

    Updates follow the same push workflow. Veza processes the full payload and replaces the contents of that data source.

    Open Authorization API
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"MyCMDB","custom_template":"cmdb"}'
    "cmdb_instances": [
      {
        "name": "Freshservice",
        "cmdb_type": "Freshservice",
        "configuration_items": [],
        "csc_global_config": {}
      }
    ]
    "configuration_items": [
      {
        "id": "ci-1001",
        "name": "web-server-01",
        "cmdb_asset_type": "Server",
        "cmdb_id": "1001",
        "cmdb_url": "https://cmdb.example.com/ci/1001",
        "status": "active",
        "asset_tag": "ASSET-001",
        "serial_number": "SN-44120",
        "location": "IAD1",
        "department": "Engineering",
        "cost_center": "eng-platform",
        "environment": "production",
        "is_active": true,
        "custom_properties": {}
      }
    ]
    "csc_global_config": {
      "ownerIdColumnName": "Managed By",
      "assetIdColumnName": "Host Name",
      "assetTypeColumnName": "Asset Type",
      "ownerNodeType": "OktaUser",
      "ownerIdProperty": "email",
      "assetConnections": [
        {
          "assetTypeValue": "AWS S3 Bucket",
          "assetNodeType": "S3Bucket",
          "assetPropertyName": "name"
        }
      ]
    }
    "custom_property_definition": {
      "cmdb_instances": [
        {
          "cmdb_type": "Freshservice",
          "configuration_item_properties": {
            "owner_external_id": "STRING",
            "patch_group": "STRING"
          }
        }
      ]
    }

    This template does not support . Every push replaces the contents of the data source.

    Sample payloads

    Generic example

    This example submits two configuration items with owner and asset correlation values, and declares one custom property.

    Real-world example: Freshservice

    The Veza Freshservice integration uses two templates from one connection. It submits agents and their roles through the template, and the Freshservice asset inventory through this one.

    Freshservice lets each tenant define its own asset types, so the integration reads the asset type catalog from the Freshservice API and uses those names verbatim as cmdb_asset_type. A tenant that tracks laptops, servers, and cloud storage produces those values with no mapping step. Because the names come from the customer rather than from Veza, the correlation configuration is supplied by the administrator when they set up the integration rather than being fixed in the connector.

    Key patterns from this integration:

    • One instance per connection. The integration submits a single

    Top-level payload

    CMDB instances

    CMDB instance properties

    Configuration items

    Configuration item properties

    Asset types

    Correlating owners and assets

    Reserved custom property keys

    Correlation configuration

    csc_global_config uses camel case field names. Every other field in this template uses lowercase with underscores.

    How resolution behaves

    Custom property definitions

    Creating and updating a CMDB

    Custom Application with SCIM
    Custom Application with Send REST Payload
    CSV Column Mapping
    Uploading findings as a CSV file
    CSV Upload Notifications

    Common

    Shared base classes, enums and identity-mapping submission types used across the OAA templates.

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • PROPERTY_NAME_REGEX


    Helper function to simplify appending.

    Handles multiple cases:

    cmdb_instances
    entry and one configuration item per Freshservice asset.
  • Asset types come from the customer's own catalog, so cmdb_asset_type holds whatever the tenant has configured rather than a Veza-defined value.

  • is_active is derived, not copied. Freshservice records a detailed asset state, and the integration treats only assets in use as active.

  • The item ID becomes the asset correlation value when the administrator has configured an asset ID column, which lets the configuration item and the cloud resource it describes share an identifier.

  • Correlation fields are administrator-supplied. Freshservice exposes display labels rather than fixed field names, so the column names in csc_global_config are whatever the tenant calls them.

  • csc_global_config

    object

    Correlation configuration for resolving owners and assets

    cmdb_id

    string

    The item's native identifier in the source system (optional)

    cmdb_url

    string

    Link to the item in the source system (optional)

    status

    string

    Status as reported by the source system (optional)

    asset_tag

    string

    Asset tag (optional)

    serial_number

    string

    Serial number (optional)

    location

    string

    Location (optional)

    department

    string

    Department (optional)

    cost_center

    string

    Cost center (optional)

    environment

    string

    Environment, for example production (optional)

    is_active

    boolean

    Whether the item is currently in service

    custom_properties

    dictionary

    Custom properties validated against configuration_item_properties, plus the two reserved correlation keys

    ownerNodeType

    string

    The Veza entity type to search for the owner, for example OktaUser

    ownerIdProperty

    string

    The property on that entity type to match owner_external_id against, for example email

    assetConnections

    array

    Maps asset type values to Veza entity types. See below

    CMDB instance
    Custom property definitions
    configuration item
    Asset types
    incremental updates
    Custom Application
    base is None: starts a list
  • addition is list: extends base with list

  • addition is anything else: append element to list

  • Args:

    • base (List or None): base list to append to, can be None

    • addition (*): What to append to the list

    Returns:

    • list: will always return a list


    Returns a list of unique strings from input list case insensitive

    Returns the unique list of strings from input list in a case insensitive manner. For duplicate strings with different cast (e.g. "STRING" and "string") the case of the first occurrence is returned.

    Args:

    • input (list): list of strings

    Returns:

    • list: list of unique strings


    Veza supported IdP provider types.


    Node types for entity owners


    Supported types for custom properties on OAA entities such as application, resource, and identity.


    Identity mapping match type.

    Corresponds to IdentityMapping.Type in identitymapping.proto.


    Identity mapping mode.

    Corresponds to IdentityMapping.Mode in identitymapping.proto.


    Identity mapping transformation applied to identity values before matching.

    Corresponds to IdentityMapping.Transformations in identitymapping.proto.


    Identity property used as source or destination in a property matcher.

    Corresponds to IdentityMapping.Property in identitymapping.proto.


    Base class for CustomProvider.



    Veza Tag data model.

    Args:

    • key (str): key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only.

    Attributes:

    • key (str): key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str): Value for tag, will appear in Veza as key:value. Must be letters, numbers and the special characters @,._ only.



    Identity mapping configuration submission.

    Top-level container for identity mapping configuration in an OAA payload.

    Args:

    • use_email (bool): Whether to use email for identity mapping. Defaults to False.

    • operation (str, optional): Operation type for this configuration.

    Attributes:

    • use_email (bool): Whether to use email for identity mapping. Default False.

    • mappings (list[IdentityMappingSubmission]): List of identity mappings.

    • operation (str): Operation type. Default None.


    Add an identity mapping.

    Args:

    • destination_datasource_type (str): Destination datasource type.

    • destination_datasource_oaa_type (str): Destination datasource OAA app type.

    • mapping_type (str): Mapping type. Use IdentityMappingType for valid values.

    • mapping_mode (str, optional): Mapping mode. Use IdentityMappingMode for valid values. Defaults to "".

    • transformations (list[str], optional): List of transformations. Use IdentityMappingTransformation for valid values. Defaults to None.

    • custom_value (str, optional): Custom value. Defaults to "".

    Returns:

    • IdentityMappingSubmission: The new mapping.


    Return the dictionary representation.


    Identity mapping submission.

    Represents a single identity mapping configuration entry.

    Args:

    • destination_datasource_type (str): Destination datasource type.

    • destination_datasource_oaa_type (str): Destination datasource OAA app type.

    • mapping_type (str): Mapping type (serialized as type). Use IdentityMappingType for valid values.

    • mapping_mode (str, optional): Mapping mode (serialized as mode). Use IdentityMappingMode for valid values. Defaults to "".

    • transformations (list[str], optional): List of transformations. Use IdentityMappingTransformation for valid values. Defaults to None.

    • custom_value (str, optional): Custom value. Defaults to "".

    Attributes:

    • destination_datasource_type (str): Destination datasource type.

    • destination_datasource_oaa_type (str): Destination datasource OAA app type.

    • mapping_type (IdentityMappingType): Mapping type.

    • mapping_mode (IdentityMappingMode): Mapping mode.

    • transformations (list[IdentityMappingTransformation]): List of transformations.

    • custom_value (str): Custom value.

    • property_matchers (list[IdentityMappingPropertyMatchersSubmission]): Property matchers.

    • destination_datasources (list[IdentityMappingDestinationDatasourceSubmission]): Destination datasources.


    Add a destination datasource.

    Args:

    • datasource_type (str): Datasource type.

    • oaa_type (str): OAA app type.

    Returns:

    • IdentityMappingDestinationDatasourceSubmission: The new destination datasource.


    Add a property matcher.

    Args:

    • source_property (str): Source property to match on. Use IdentityMappingProperty for valid values.

    • destination_property (str): Destination property to match against. Use IdentityMappingProperty for valid values.

    • custom_source_property (str, optional): Custom source property name, used when source_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".

    • custom_destination_property (str, optional): Custom destination property name, used when destination_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".

    Returns:

    • IdentityMappingPropertyMatchersSubmission: The new property matcher.


    Return the dictionary representation.


    Identity mapping property matcher.

    Defines how source and destination properties are matched.

    Args:

    • source_property (str): Source property to match on. Use IdentityMappingProperty for valid values.

    • destination_property (str): Destination property to match against. Use IdentityMappingProperty for valid values.

    • custom_source_property (str, optional): Custom source property name, used when source_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".

    • custom_destination_property (str, optional): Custom destination property name, used when destination_property is IdentityMappingProperty.CUSTOM_PROPERTY. Defaults to "".


    Return the dictionary representation.


    Identity mapping destination datasource.

    Specifies a destination datasource for an identity mapping.

    Args:

    • datasource_type (str): Datasource type (serialized as type).

    • oaa_type (str): OAA app type (serialized as oaa_app_type).


    Return the dictionary representation.

    function append_helper

    function unique_strs

    class IdPProviderType

    class OAAOwnerType

    class OAAPropertyType

    class IdentityMappingType

    class IdentityMappingMode

    class IdentityMappingTransformation

    class IdentityMappingProperty

    class Provider

    method __init__

    method serialize

    class Tag

    method __init__

    class EntityOwner

    method __init__

    class IdentityMappingConfigurationSubmission

    method __init__

    method add_mapping

    method to_dict

    class IdentityMappingSubmission

    method __init__

    method add_destination_datasource

    method add_property_matcher

    method to_dict

    class IdentityMappingPropertyMatchersSubmission

    method __init__

    method to_dict

    class IdentityMappingDestinationDatasourceSubmission

    method __init__

    method to_dict

    {
      "cmdb_instances": [
        {
          "name": "Example CMDB",
          "cmdb_type": "ExampleCMDB",
          "csc_global_config": {
            "ownerIdColumnName": "Managed By",
            "assetIdColumnName": "Host Name",
            "assetTypeColumnName": "Asset Type",
            "ownerNodeType": "OktaUser",
            "ownerIdProperty": "email",
            "assetConnections": [
              {
                "assetTypeValue": "AWS S3 Bucket",
                "assetNodeType": "S3Bucket",
                "assetPropertyName": "name"
              }
            ]
          },
          "configuration_items": [
            {
              "id": "ci-1001",
              "name": "web-server-01",
              "cmdb_asset_type": "Server",
              "cmdb_id": "1001",
              "cmdb_url": "https://cmdb.example.com/ci/1001",
              "status": "active",
              "asset_tag": "ASSET-001",
              "serial_number": "SN-44120",
              "location": "IAD1",
              "department": "Engineering",
              "cost_center": "eng-platform",
              "environment": "production",
              "is_active": true,
              "custom_properties": {
                "owner_external_id": "alice@example.com",
                "asset_external_id": "web-server-01",
                "patch_group": "weekly"
              }
            },
            {
              "id": "ci-1002",
              "name": "reports-archive",
              "cmdb_asset_type": "AWS S3 Bucket",
              "cmdb_id": "1002",
              "status": "active",
              "is_active": true,
              "custom_properties": {
                "owner_external_id": "bob@example.com",
                "asset_external_id": "reports-archive"
              }
            }
          ]
        }
      ],
      "custom_property_definition": {
        "cmdb_instances": [
          {
            "cmdb_type": "ExampleCMDB",
            "configuration_item_properties": {
              "owner_external_id": "STRING",
              "patch_group": "STRING"
            }
          }
        ]
      }
    }
    {
      "cmdb_instances": [
        {
          "name": "Freshservice",
          "cmdb_type": "Freshservice",
          "csc_global_config": {
            "ownerIdColumnName": "Managed By",
            "assetIdColumnName": "Host Name",
            "assetTypeColumnName": "Asset Type",
            "ownerNodeType": "OktaUser",
            "ownerIdProperty": "email",
            "assetConnections": [
              {
                "assetTypeValue": "AWS S3 Bucket",
                "assetNodeType": "S3Bucket",
                "assetPropertyName": "name"
              },
              {
                "assetTypeValue": "AWS Security Group",
                "assetNodeType": "EC2SecurityGroup",
                "assetPropertyName": "name"
              }
            ]
          },
          "configuration_items": [
            {
              "id": "asset-4471",
              "name": "LT-4471",
              "cmdb_asset_type": "Laptop",
              "cmdb_id": "4471",
              "cmdb_url": "https://example.freshservice.com/cmdb/items/4471",
              "status": "In Use",
              "asset_tag": "ASSET-4471",
              "serial_number": "C02XL0ABCDEF",
              "is_active": true,
              "custom_properties": {
                "owner_external_id": "alice@example.com"
              }
            },
            {
              "id": "reports-archive",
              "name": "reports-archive",
              "cmdb_asset_type": "AWS S3 Bucket",
              "cmdb_id": "4482",
              "status": "In Use",
              "is_active": true,
              "custom_properties": {
                "owner_external_id": "bob@example.com",
                "asset_external_id": "reports-archive"
              }
            }
          ]
        }
      ],
      "custom_property_definition": {
        "cmdb_instances": [
          {
            "cmdb_type": "Freshservice",
            "configuration_item_properties": {
              "owner_external_id": "STRING"
            }
          }
        ]
      }
    }
    append_helper(base, addition)
    unique_strs(input: 'list') → list
    __init__(name, custom_template)
    serialize()
    __init__(key: 'str', value: 'str' = '') → None
    __init__(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    __init__() → None
    add_mapping(
        destination_datasource_type: 'str',
        destination_datasource_oaa_type: 'str',
        mapping_type: 'str',
        mapping_mode: 'str' = '',
        transformations: 'List[str]' = None,
        custom_value: 'str' = ''
    ) → IdentityMappingSubmission
    to_dict() → dict
    __init__(
        destination_datasource_type: 'str',
        destination_datasource_oaa_type: 'str',
        mapping_type: 'str',
        mapping_mode: 'str' = '',
        transformations: 'List[str]' = None,
        custom_value: 'str' = ''
    ) → None
    add_destination_datasource(
        datasource_type: 'str',
        oaa_type: 'str'
    ) → IdentityMappingDestinationDatasourceSubmission
    add_property_matcher(
        source_property: 'str',
        destination_property: 'str',
        custom_source_property: 'str' = '',
        custom_destination_property: 'str' = ''
    ) → IdentityMappingPropertyMatchersSubmission
    to_dict() → dict
    __init__(
        source_property: 'str',
        destination_property: 'str',
        custom_source_property: 'str' = '',
        custom_destination_property: 'str' = ''
    ) → None
    to_dict() → dict
    __init__(datasource_type: 'str', oaa_type: 'str') → None
    to_dict() → dict

    Custom Properties

    Applying additional metadata to OAA entities

    In addition to built-in fields such as last_login_at, OAA supports custom-named properties for users, resources, groups, and other entities in a payload. Custom properties are validated against a set of custom property definitions as part of the JSON payload.

    To use custom properties:

    1. Include a definition of all properties as part of the payload push. The definition sets the type for the property.

    2. Set the custom properties for each object.

    Built-in properties (such as last_login

    ,
    created_at
    , and
    is_active
    for local users) enrich Veza graph entities with additional metadata. These built-in properties are described in the template documentation for
    and
    .

    If a built-in property doesn’t exist for the provider you are modeling, you can define custom properties in the OAA payload. This can enable sophisticated queries on many possible fields (such as encryption_enabled, password_last_used_at). Custom properties have a declared data type and are indexed and filterable, like any built-in property.

    For example, you could use the custom string property "state" for an app that can be either "active," "suspended," or "disabled." If there's only one state, you could instead use a boolean ("active": "false").

    Custom Properties are defined as part of the custom_property_definition section and require a type. Typing the data allows Veza to provide a better index and search experience. For example, the TIMESTAMP type enables date-relative filters such as "in the last 30 days."

    Allowed types are NUMBER, STRING, STRING_LIST, TIMESTAMP, and BOOLEAN.

    • A type is required and permanent.

    • Dates must be in RFC3339 format, which can include a timezone offset or use UTC (2021-01-01T22:47:31-07:00, 2021-01-01T22:47:31Z).

    • The maximum length of a string is 4096 characters.

    In the Veza UI, underscores in property names are replaced by spaces, and first letters are capitalized (is_licensed > Is Licensed).

    If a custom property name collides with an existing built-in property, Veza will add the "Custom" prefix (ID > Custom Id).

    In the Query Builder API, custom properties are prefixed with custom_ in responses and must be prefixed with custom_ when used in filter statements.

    Once pushed, properties and types can't be altered. You can re-submit the payload with additional custom property definitions to add new properties.

    • Property values on entities can be modified by pushing a complete payload with new custom_properties or using incremental update operations.

    • The provider must be deleted and pushed again to remove properties from a definition or change their types.

    • The original custom property definition is not required in future submissions but should be saved for later reference.

    Here are some example custom property definitions for the custom application and custom identity provider templates.

    The Python SDK also supports creating and setting custom properties.

    A custom property definition sets possible properties, their types, and the application or resource type they can apply to. The following entities can have custom properties:

    Entity
    Key
    Notes

    Custom Application

    application_properties

    Scoped by application_type

    Custom User

    local_user_properties

    Custom Group

    local_group_properties

    The following example shows a custom property definition for GitLab:

    Properties are set on users and resources in custom_properties:

    Entity
    Key

    Custom IdP Domain

    domain_properties

    Custom IdP User

    user_properties

    Custom IdP Group

    group_properties

    Use cases

    app = CustomApplication(name="Demo", application_type="Demo")
    # Define a new local user string property `email`
    app.property_definitions.define_local_user_property("email", OAAPropertyType.STRING)
    
    local_user = app.add_local_user(name="name", unique_id="user_id")
    # set the property by name
    local_user.set_property("email", "user@example.com")
      "custom_property_definition": {
        "applications": [
          {
            "application_type": "GitLab",
            "application_properties": {},
            "local_user_properties": {
              "id": "NUMBER",
              "bot": "BOOLEAN",
              "is_licensed": "BOOLEAN",
              "state": "STRING"
            },
            "local_group_properties": {},
            "local_role_properties": {},
            "role_assignment_properties": {
              "assigned_at": "TIMESTAMP",
              "expires_at": "TIMESTAMP"
            },
            "local_access_creds_properties": {
              "scope": "STRING",
              "rotation_period_days": "NUMBER"
            },
            "resources": [
              {
                "resource_type": "project",
                "properties": {
                  "id": "NUMBER",
                  "visibility": "STRING"
                }
              }
            ]
          }
        ]
      }
    {
      "name": "support-bot",
      "identities": ["support@cookie.ai"],
      "groups": null,
      "is_active": true,
      "created_at": "2022-01-25T18:55:19.146Z",
      "last_login_at": null,
      "deactivated_at": null,
      "password_last_changed_at": null,
      "tags": [],
      "custom_properties": {
        "id": 7,
        "is_licensed": false,
        "state": "active",
        "bot": true
      }
    }
    {
      "custom_property_definition": {
        "domain_properties": null,
        "group_properties": {
          "group_lead": "STRING"
        },
        "user_properties": {
          "birthday": "TIMESTAMP",
          "description": "STRING",
          "last_login": "TIMESTAMP",
          "is_licensed": "BOOLEAN",
          "region": "STRING"
        }
      },
      "name": "My IdP",
      "id": "custom_idp",
      "domains": [
        {
          "name": "domain.biz"
        }
      ],
      "users": [
        {
          "name": "Colby Smith",
          "custom_properties": {
            "is_licensed": false,
            "region": "US-West"
          }
        }
      ]
    }

    Custom property types

    Modifying custom properties

    OAA custom property examples

    Custom properties with oaaclient Python SDK

    Custom properties for a custom application

    Custom properties for a custom identity provider

    applications
    identity providers

    Application Outline

    This document provides a high-level overview and examples for getting started with a new OAA connector to integrate Veza with SaaS applications, infrastructure systems, custom-built applications, and other systems. These examples use Python and the oaaclient SDK.

    When developing a connector, the source systems and customer needs can require changes to code flow for different deployment scenarios. The overall goals, best practices, and flow will apply for most integrations:

    The sample code was written with the following goals in mind:

    • Connector should be easy to run from automation platforms and the command line.

      • Parameters are passed through environment variables as well as command line flags. This makes the code easier to package into containers or serverless stacks and control through outside configuration. Connectors by nature require secrets such as the Veza API key. Managing these through variables affords additional options for secrets management.

    Custom Role

    local_role_properties

    Role Assignment

    role_assignment_properties

    Properties on the role assignment itself, not the role

    Access Credential

    local_access_creds_properties

    Custom Resource

    resources

    Scoped by resource_type

  • Connectors do not require state:

    • Connectors do not require any persistent data between runs.

    • There is no special invocation for the first run or subsequent runs.

    • The connector handles all of the logic for provider and data source creation internally, as needed, or by discovering existing ones.

      • Data Source name should be unique to the discovered environment. This can be achieved by including a hostname or instance ID in the data source name: discoverable by the code and consistent between runs. This ensures that two instances of the same connector do not interfere with each other if discovering separate instances of the application. When such a property cannot be determined, a command line parameter is an option.

  • Connector code is importable:

    • The flexibility to import connector code into another piece of Python code enables a setup wrapper to handle job management tasks such as:

      • Secrets management

      • Output logging

      • Other configurations required by the environment

    • A separate run function implements connector end-to-end logic. This can be imported and invoked by providing the necessary parameters. The main function that runs when invoked from the command line should only process command line inputs and environment variables for setup.

  • The exact flow of the connector can change to meet specific requirements, but the general steps are as follows:

    1. Process and validate configuration parameters. Ensure you have supplied all necessary values such as host names, user names, and API keys.

    2. Call the main run function with all the required and optional parameters.

    3. Initialize the oaaclient connection to the Veza tenant. Initializing the client verifies that the Veza URL and API key are valid before starting any application discovery.

    4. Create an instance of the oaaclient.templates.CustomApplication to populate with the application information.

    5. Connect to the system and perform discovery of required entities:

      1. The discovery order for users, groups, roles, and so on can be changed based on relationships and interface.

      2. Populate the CustomApplication instance with the identity, roles and permissions, resources, and authorization information.

    6. Check if Provider and Data Source exist on Veza. Create them if they do not exist.

    7. Push the application to the Data Source. The SDK creates the JSON payload from the CustomApplication instance.

      1. Process any returned warnings or errors.

    8. Exit.

    1. Update the Provider Name, App Type, and Application Name based on the source system. These values will typically be set to the product name. The data source name must be unique - check that an appropriate distinguishing value such as hostname is included in the data source name. For more information on naming, see Providers, Data Sources, Names and Types

    2. Define any custom properties needed in the __init__ method. Properties must be defined on the CustomApplication entities before setting them.

    3. Implement the discovery steps for the discover() function to collect Users, Groups, Roles, and any resources for the application. As the entities are discovered, add them to the CustomApplication object using the appropriate .

    4. Run the connector to validate the output in Veza.

    5. Automate the connector to run on a regular schedule.

    The code below can serve as a template and the comments explain the reasoning beyond the patterns.

    Code goals

    oaa-app.py
    #!/usr/bin/env python3
    from __future__ import annotations
    
    import argparse
    import json
    import logging
    import os
    import sys
    
    import requests
    from requests.exceptions import HTTPError, RequestException
    
    from oaaclient.client import OAAClient, OAAClientError
    from oaaclient.templates import CustomApplication, OAAPermission, OAAPropertyType, LocalUser
    import oaaclient.utils as oaautils
    
    """
    Logging in connectors is very important. Establishing a local logging function here
    allows the connector log even if its imported into another block of code
    """
    logging.basicConfig(
    format='%(asctime)s %(levelname)s: %(message)s', level=logging.INFO)
    log = logging.getLogger(__name__)
    
    """
    The main logic for connecting to the destination application.
    Authorization data collection and OAA template population should be structured into a class.
    The class can store the authentication tokens making connections through an API or SDK easier.
    The class should also instantiate the OAA CustomApplication or CustomIdP class
    to manage populating all the identity, resource and authorization data.
    """
    class OAAConnector():
        APP_TYPE="SampleApp"
        def __init__(self, auth_token: str) -> None:
            self.auth_token = auth_token
    
    
            # Set the application name and type. The type will generally be the vendor or product.
            # The App Name can be the same, or contain additional context like the instance name.
            app_name = "My App - West"
            self.app = CustomApplication(app_name, application_type=self.APP_TYPE)
    
            # declaring custom properties as part of the `__init__` keeps them together
            self.app.property_definitions.define_local_user_property("email", OAAPropertyType.STRING)
            self.app.property_definitions.define_local_user_property("has_mfa", OAAPropertyType.BOOLEAN)
    
        """
        A `discover` method that starts the discovery cycle.
        The discovery cycle should be invoked separately from the init.
        More complex connectors may have additional setup steps between init and discovery
        """
        def discover(self) -> None:
            """Discovery method"""
            log.info(
            "Start App discovery")  # Start and stop log messages provide progress as discovery proceeds
            self._discover_users()
            self._discover_roles()
            log.info("Finished App discovery")
            return
    
        """
        Smaller functions to perform portions of the discovery like users, groups, roles
        should be private `_` functions to imply that they should not be run alone,
        unless care is taken to ensure no dependencies.
        For example, discovery of roles may assume that users are already discovered.
        """
        def _discover_users(self) -> None:
            log.info("Start user discovery")
    
            # perform user discovery, for example process each user returned from an API call
            for user in self._api_get("/Users"):
                local_user = self.app.add_local_user(id=user["id"], name=user["name"])
                local_user.is_active = user["active"]
                local_user.set_property("has_mfa", user["mfa_enabled"])
    
            log.info("Finished user discovery")
            return
    
        def _discover_roles(self) -> None:
            log.info("Start role discovery")
            # perform user discovery
            log.info("Finished role discovery")
            return
    
        """
        Any required methods to interface with the application should be defined
        as part of the class. Not all connectors need these methods, as they may use
        other SDKs to interface with the application.
        """
        def _api_get(self, path: str) -> dict:
            # implement logic to make API call, process results, handle errors, retries ect.
            # Could be done with a vendor SDK, SQL, or any method supported by the application
            return {}
    
    
    """
    A run function that is separate from `main` makes it easy to import the connector
    into another piece of Python code. This may be useful to call the connector from
    code that retrieves secrets or manages the job in other ways.
    All necessary parameters should be taken in through the `run` function
    """
    def run(veza_url: str, veza_api_key: str, app_key: str, **config_args) -> None:
    
        # Process any configuration arguments
        if config_args.get("debug"):
            log.setLevel(logging.DEBUG)
            logging.getLogger("urllib3").setLevel(logging.INFO)
            log.info("Enabling debug logging")
        else:
            log.setLevel(logging.INFO)
    
        save_json = config_args.get("save_json", False)
        if not isinstance(save_json, bool):
            raise TypeError("save_json argument must be boolean")
    
        # Connect to the Veza instance before discovery to validate that the credentials are valid
        try:
            conn = OAAClient(url = veza_url, api_key = veza_api_key)
        except OAAClientError as error:
            log.error(f"Unable to connect to Veza {veza_url}")
            log.error(error.message)
            # run function should raise any exception so that they can be handled by the parent code, never exit
            raise error
    
        # Initialize the connector class and run discovery
        try:
            app = OAAConnector(auth_token=app_key)
            app.discover()
        except RequestException as e:
        # process possible exceptions from the app discovery
            log.error("Error during discovery")
            log.error(f"{e} - {e.response.status_code} {e.response.text}")
            raise e
    
        # After discovery is complete, set up the Provider and Data Source to push the data to
    
        # Provider name should be consistent with the vendor and application
        provider_name = "My App"
        provider = conn.get_provider(provider_name)
    
        if provider:
            log.info("found existing provider")
        else:
            log.info(f"creating provider {provider_name}")
            provider = conn.create_provider(provider_name, "application", base64_icon=APP_SVG_B64)
        log.info(f"provider: {provider['name']} ({provider['id']})")
    
        # Data Source name should be unique to the instance of the app that is discovered but consistent.
        # For example the hostname of the application or deployment name. Do not use something that will change.
        data_source_name = f"App - {app.unique_identifier}"
    
        try:
            log.info("uploading application data")
            response = conn.push_application(provider_name,
                                            data_source_name = data_source_name,
                                            application_object = app.app,
                                            save_json = save_json
                                            )
            # An OAA Push can succeed with warnings, you can log out the warnings
            if response.get("warnings", None):
                log.warning("Push succeeded with warnings:")
                for e in response["warnings"]:
                    log.warning(e)
            log.info("success")
        except OAAClientError as error:
        # if there is an issue with the OAA payload the error details should contain useful information to help resolve the problem
            log.error(f"{error.error}: {error.message} ({error.status_code})")
            if hasattr(error, "details"):
                for detail in error.details:
                    log.error(detail)
            raise error
    
        return
    
    """
    Setting an application icon helps visually identify the app in the Veza UI.
    A Base64 encoding of an SVG or PNG in the app code is an option.
    You can also import an icon from a file with `oaaclient.utils.encode_icon_file`.
    """
    APP_SVG_B64 = """
    PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pg0KPCFET0NUWVBFIHN2ZyBQVUJMSUMgIi0vL1czQy8vRFRE
    IFNWRyAxLjEvL0VOIiAiaHR0cDovL3d3dy53My5vcmcvR3JhcGhpY3MvU1ZHLzEuMS9EVEQvc3ZnMTEuZHRkIj4NCjxzdmcgd2lkdGg9IjQwMCIgaGVpZ2h0
    PSI0MDAiIHZpZXdCb3g9IjAgMCAyMDAgMjAwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPg0KICA8cGF0aCBmaWxsPSJyZWQiIHN0cm9r
    ZT0iIzAwMCIgc3Ryb2tlLXdpZHRoPSIyLjUiIGQ9Ik0xNjggMTY4SDMyVjMyaDEzNnoiLz4NCjwvc3ZnPg0K
    """
    
    """
    The main entry point should only deal with processing parameters and invoking
    the run function. No OAA or application discovery should happen during the main
    function. All required parameters should be configurable through the OS
    environment. It should be possible to run the connector from the command line
    with no arguments.
    """
    def main():
        """
        process command line and OS environment variables, then call `run`
        """
        parser = argparse.ArgumentParser(description = "OAA Connector")
        # using the `default=os.getenv()` pattern makes it easier to get parameters from command line or OS environment
        parser.add_argument("--veza-url", default=os.getenv("VEZA_URL"), help="the URL of the Veza instance")
        parser.add_argument("--debug", action="store_true", help="Set the log level to debug")
        parser.add_argument("--save-json", action="store_true", help="Save OAA JSON payload to file")
        args = parser.parse_args()
    
        # Secrets should only be passed in through ENV
        veza_api_key = os.getenv("VEZA_API_KEY")
        veza_url = args.veza_url
        save_json = args.save_json
    
        if not veza_api_key:
            oaautils.log_arg_error(log, None, "VEZA_API_KEY")
        if not veza_url:
            oaautils.log_arg_error(log, "--veza-url", "VEZA_URL")
    
        # ensure required variables are provided
        if None in [veza_api_key, veza_url]:
            log.error(f"missing one or more required parameters")
            sys.exit(1)
    
        try:
            run( veza_url=veza_url, veza_api_key=veza_api_key, save_json=save_json, debug=args.debug)
        except (OAAClientError, RequestException):
            log.error("Exiting with error")
            sys.exit(1)
    
    
    if __name__ == "__main__":
        # replace the log with the root logger if running as main
        log = logging.getLogger()
        logging.basicConfig(format='%(asctime)s %(levelname)s: %(message)s', level=logging.INFO)
    
        main()

    High-level code flow

    Implementing from the example

    Code walkthrough for custom application

    Sample Apps

    Usage examples for the oaaclient Python SDK

    The examples on this page can be used as a starting point for building new connectors for custom applications. You should also refer to the current list of for real-world examples, and to check if an integration already exists for your use case.

    To run the code, you will need to export environment variables for the Veza URL, user and API keys, for example:

    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Body
    namestringOptional
    custom_templatestringOptional
    provisioningbooleanOptional
    push_typeinteger · enumOptional
    internal_app_namestringOptional
    configuration_jsonstringOptional
    data_plane_idstringOptional
    custom_templatesstring[]Optional
    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional

    For external OAA, how to manage lifecycle management requests

    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    Responses
    200

    OK

    application/json
    idstringOptional

    Unique identifier for the provider instance.

    external_idstringOptional

    External identifier for the provider, typically set by the integration that created it.

    namestringOptional

    Display name of the provider.

    custom_templatestringOptional

    The OAA template type used to create this provider (e.g., "application", "idp").

    custom_templatesstring[]Optional

    List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").

    stateinteger · enumOptional

    Current provider state.

    application_typesstring[]Optional

    Application type classifications for this provider.

    resource_typesstring[]OptionalDeprecated

    Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.

    idp_typesstring[]Optional

    Identity provider type classifications (if this provider represents an IdP).

    file_system_typesstring[]Optional

    File system type classifications (if this provider represents a file system).

    hris_typesstring[]Optional

    HRIS system type classifications (if this provider represents an HR system).

    principal_typesstring[]Optional

    Principal (identity) type classifications for this provider.

    secret_store_typesstring[]Optional
    host_typesstring[]Optional
    schema_definition_jsonstring · bytesOptional
    provisioningbooleanOptional

    Whether provisioning (write-back) operations are enabled for this provider.

    push_typeinteger · enumOptional
    rbac_idstringOptional
    internal_app_namestringOptional
    configuration_jsonstringOptional

    JSON string containing the provider's connection configuration parameters.

    data_plane_idstringOptional

    Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.

    lifecycle_management_stateinteger · enumOptional

    Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.

    team_idstringOptional

    Identifier of the team that owns this provider instance.

    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional

    For external OAA, how to manage lifecycle management requests

    cmdb_typesstring[]Optional
    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom
    POST /api/v1/providers/custom HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 2025
    
    {
      "name": "text",
      "custom_template": "text",
      "provisioning": true,
      "push_type": 1,
      "internal_app_name": "text",
      "configuration_json": "text",
      "data_plane_id": "text",
      "custom_templates": [
        "text"
      ],
      "csv_mapping_configuration": {
        "template_type": "text",
        "column_mappings": [
          {
            "column_name": "text",
            "destination_type": "text",
            "destination_property": "text",
            "custom_property": {
              "name": "text",
              "type": 1,
              "lcm_unique_identifier": true
            },
            "as_list": true,
            "template": "text",
            "property_type": 1,
            "is_required": true
          }
        ],
        "application": {
          "application_name": "text",
          "application_type": "text",
          "identity": [
            "text"
          ],
          "resource_type": "text",
          "okta_app_id": "text"
        },
        "advanced": {
          "list_delimiter": "text"
        },
        "idp": {
          "idp_type": "text",
          "domain": "text"
        },
        "hris": {
          "hris_name": "text",
          "hris_type": "text",
          "hris_url": "text",
          "hris_identity_mapping": {
            "mappings": [
              {
                "destination_datasource_type": "text",
                "destination_datasource_oaa_app_type": "text",
                "type": 1,
                "mode": 1,
                "transformations": [
                  1
                ],
                "custom_value": "text",
                "property_matchers": [
                  {
                    "source_property": 1,
                    "destination_property": 1,
                    "custom_source_property": "text",
                    "custom_destination_property": "text"
                  }
                ],
                "id_matchers": [
                  {
                    "source_id": "text",
                    "destination_id": "text"
                  }
                ],
                "destination_datasources": [
                  {
                    "type": "text",
                    "oaa_app_type": "text"
                  }
                ],
                "property_match_operator": 1
              }
            ],
            "use_email": true
          },
          "hris_provisioning_source": true
        },
        "cmdb": {
          "cmdb_instance_name": "text",
          "cmdb_instance_type": "text",
          "csc_global_config": {
            "owner_id_column_name": "text",
            "asset_id_column_name": "text",
            "asset_type_column_name": "text",
            "owner_node_type": "text",
            "owner_id_property": "text",
            "asset_connections": [
              {
                "asset_type_value": "text",
                "asset_node_type": "text",
                "asset_property_name": "text"
              }
            ]
          }
        },
        "secret_store": {
          "secret_store_name": "text",
          "secret_store_type": "text",
          "vault_type": "text"
        }
      },
      "secret_references": [
        {
          "secret_id": "text",
          "secret_mapping": {
            "type": 1,
            "mapping": "text"
          },
          "vault_id": "text"
        }
      ],
      "external_lifecycle_management_type": 1,
      "notification_preferences": {
        "enabled": true,
        "subscribed_events": [
          1
        ],
        "notify_integration_owner": true,
        "additional_recipients": [
          "text"
        ],
        "delivery_methods": [
          {
            "type": 1,
            "id": "text"
          }
        ]
      }
    }
    {
      "value": {
        "id": "text",
        "external_id": "text",
        "name": "text",
        "custom_template": "text",
        "custom_templates": [
          "text"
        ],
        "state": 1,
        "application_types": [
          "text"
        ],
        "idp_types": [
          "text"
        ],
        "file_system_types": [
          "text"
        ],
        "hris_types": [
          "text"
        ],
        "principal_types": [
          "text"
        ],
        "secret_store_types": [
          "text"
        ],
        "host_types": [
          "text"
        ],
        "schema_definition_json": "text",
        "provisioning": true,
        "push_type": 1,
        "rbac_id": "text",
        "internal_app_name": "text",
        "configuration_json": "text",
        "data_plane_id": "text",
        "lifecycle_management_state": 1,
        "team_id": "text",
        "csv_mapping_configuration": {
          "template_type": "text",
          "column_mappings": [
            {
              "column_name": "text",
              "destination_type": "text",
              "destination_property": "text",
              "custom_property": {
                "name": "text",
                "type": 1,
                "lcm_unique_identifier": true
              },
              "as_list": true,
              "template": "text",
              "property_type": 1,
              "is_required": true
            }
          ],
          "application": {
            "application_name": "text",
            "application_type": "text",
            "identity": [
              "text"
            ],
            "resource_type": "text",
            "okta_app_id": "text"
          },
          "advanced": {
            "list_delimiter": "text"
          },
          "idp": {
            "idp_type": "text",
            "domain": "text"
          },
          "hris": {
            "hris_name": "text",
            "hris_type": "text",
            "hris_url": "text",
            "hris_identity_mapping": {
              "mappings": [
                {
                  "destination_datasource_type": "text",
                  "destination_datasource_oaa_app_type": "text",
                  "type": 1,
                  "mode": 1,
                  "transformations": [
                    1
                  ],
                  "custom_value": "text",
                  "property_matchers": [
                    {
                      "source_property": 1,
                      "destination_property": 1,
                      "custom_source_property": "text",
                      "custom_destination_property": "text"
                    }
                  ],
                  "id_matchers": [
                    {
                      "source_id": "text",
                      "destination_id": "text"
                    }
                  ],
                  "destination_datasources": [
                    {
                      "type": "text",
                      "oaa_app_type": "text"
                    }
                  ],
                  "property_match_operator": 1
                }
              ],
              "use_email": true
            },
            "hris_provisioning_source": true
          },
          "cmdb": {
            "cmdb_instance_name": "text",
            "cmdb_instance_type": "text",
            "csc_global_config": {
              "owner_id_column_name": "text",
              "asset_id_column_name": "text",
              "asset_type_column_name": "text",
              "owner_node_type": "text",
              "owner_id_property": "text",
              "asset_connections": [
                {
                  "asset_type_value": "text",
                  "asset_node_type": "text",
                  "asset_property_name": "text"
                }
              ]
            }
          },
          "secret_store": {
            "secret_store_name": "text",
            "secret_store_type": "text",
            "vault_type": "text"
          }
        },
        "secret_references": [
          {
            "id": "text",
            "secret_id": "text",
            "secret_mapping": {
              "type": 1,
              "mapping": "text"
            },
            "vault_id": "text",
            "vault": {
              "id": "text",
              "name": "text",
              "vault_provider": "text",
              "insight_point_id": "text",
              "deleted": true
            }
          }
        ],
        "external_lifecycle_management_type": 1,
        "cmdb_types": [
          "text"
        ],
        "notification_preferences": {
          "enabled": true,
          "subscribed_events": [
            1
          ],
          "notify_integration_owner": true,
          "additional_recipients": [
            "text"
          ],
          "delivery_methods": [
            {
              "type": 1,
              "id": "text"
            }
          ]
        }
      }
    }
    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Body
    namestringOptional
    custom_templatestringOptional
    provisioningbooleanOptional
    push_typeinteger · enumOptional
    internal_app_namestringOptional
    configuration_jsonstringOptional
    data_plane_idstringOptional
    custom_templatesstring[]Optional
    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional

    For external OAA, how to manage lifecycle management requests

    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    Responses
    200

    OK

    application/json
    idstringOptional

    Unique identifier for the provider instance.

    external_idstringOptional

    External identifier for the provider, typically set by the integration that created it.

    namestringOptional

    Display name of the provider.

    custom_templatestringOptional

    The OAA template type used to create this provider (e.g., "application", "idp").

    custom_templatesstring[]Optional

    List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").

    stateinteger · enumOptional

    Current provider state.

    application_typesstring[]Optional

    Application type classifications for this provider.

    resource_typesstring[]OptionalDeprecated

    Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.

    idp_typesstring[]Optional

    Identity provider type classifications (if this provider represents an IdP).

    file_system_typesstring[]Optional

    File system type classifications (if this provider represents a file system).

    hris_typesstring[]Optional

    HRIS system type classifications (if this provider represents an HR system).

    principal_typesstring[]Optional

    Principal (identity) type classifications for this provider.

    secret_store_typesstring[]Optional
    host_typesstring[]Optional
    schema_definition_jsonstring · bytesOptional
    provisioningbooleanOptional

    Whether provisioning (write-back) operations are enabled for this provider.

    push_typeinteger · enumOptional
    rbac_idstringOptional
    internal_app_namestringOptional
    configuration_jsonstringOptional

    JSON string containing the provider's connection configuration parameters.

    data_plane_idstringOptional

    Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.

    lifecycle_management_stateinteger · enumOptional

    Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.

    team_idstringOptional

    Identifier of the team that owns this provider instance.

    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional

    For external OAA, how to manage lifecycle management requests

    cmdb_typesstring[]Optional
    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom
    POST /api/v1/providers/custom HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 2025
    
    {
      "name": "text",
      "custom_template": "text",
      "provisioning": true,
      "push_type": 1,
      "internal_app_name": "text",
      "configuration_json": "text",
      "data_plane_id": "text",
      "custom_templates": [
        "text"
      ],
      "csv_mapping_configuration": {
        "template_type": "text",
        "column_mappings": [
          {
            "column_name": "text",
            "destination_type": "text",
            "destination_property": "text",
            "custom_property": {
              "name": "text",
              "type": 1,
              "lcm_unique_identifier": true
            },
            "as_list": true,
            "template": "text",
            "property_type": 1,
            "is_required": true
          }
        ],
        "application": {
          "application_name": "text",
          "application_type": "text",
          "identity": [
            "text"
          ],
          "resource_type": "text",
          "okta_app_id": "text"
        },
        "advanced": {
          "list_delimiter": "text"
        },
        "idp": {
          "idp_type": "text",
          "domain": "text"
        },
        "hris": {
          "hris_name": "text",
          "hris_type": "text",
          "hris_url": "text",
          "hris_identity_mapping": {
            "mappings": [
              {
                "destination_datasource_type": "text",
                "destination_datasource_oaa_app_type": "text",
                "type": 1,
                "mode": 1,
                "transformations": [
                  1
                ],
                "custom_value": "text",
                "property_matchers": [
                  {
                    "source_property": 1,
                    "destination_property": 1,
                    "custom_source_property": "text",
                    "custom_destination_property": "text"
                  }
                ],
                "id_matchers": [
                  {
                    "source_id": "text",
                    "destination_id": "text"
                  }
                ],
                "destination_datasources": [
                  {
                    "type": "text",
                    "oaa_app_type": "text"
                  }
                ],
                "property_match_operator": 1
              }
            ],
            "use_email": true
          },
          "hris_provisioning_source": true
        },
        "cmdb": {
          "cmdb_instance_name": "text",
          "cmdb_instance_type": "text",
          "csc_global_config": {
            "owner_id_column_name": "text",
            "asset_id_column_name": "text",
            "asset_type_column_name": "text",
            "owner_node_type": "text",
            "owner_id_property": "text",
            "asset_connections": [
              {
                "asset_type_value": "text",
                "asset_node_type": "text",
                "asset_property_name": "text"
              }
            ]
          }
        },
        "secret_store": {
          "secret_store_name": "text",
          "secret_store_type": "text",
          "vault_type": "text"
        }
      },
      "secret_references": [
        {
          "secret_id": "text",
          "secret_mapping": {
            "type": 1,
            "mapping": "text"
          },
          "vault_id": "text"
        }
      ],
      "external_lifecycle_management_type": 1,
      "notification_preferences": {
        "enabled": true,
        "subscribed_events": [
          1
        ],
        "notify_integration_owner": true,
        "additional_recipients": [
          "text"
        ],
        "delivery_methods": [
          {
            "type": 1,
            "id": "text"
          }
        ]
      }
    }
    {
      "value": {
        "id": "text",
        "external_id": "text",
        "name": "text",
        "custom_template": "text",
        "custom_templates": [
          "text"
        ],
        "state": 1,
        "application_types": [
          "text"
        ],
        "idp_types": [
          "text"
        ],
        "file_system_types": [
          "text"
        ],
        "hris_types": [
          "text"
        ],
        "principal_types": [
          "text"
        ],
        "secret_store_types": [
          "text"
        ],
        "host_types": [
          "text"
        ],
        "schema_definition_json": "text",
        "provisioning": true,
        "push_type": 1,
        "rbac_id": "text",
        "internal_app_name": "text",
        "configuration_json": "text",
        "data_plane_id": "text",
        "lifecycle_management_state": 1,
        "team_id": "text",
        "csv_mapping_configuration": {
          "template_type": "text",
          "column_mappings": [
            {
              "column_name": "text",
              "destination_type": "text",
              "destination_property": "text",
              "custom_property": {
                "name": "text",
                "type": 1,
                "lcm_unique_identifier": true
              },
              "as_list": true,
              "template": "text",
              "property_type": 1,
              "is_required": true
            }
          ],
          "application": {
            "application_name": "text",
            "application_type": "text",
            "identity": [
              "text"
            ],
            "resource_type": "text",
            "okta_app_id": "text"
          },
          "advanced": {
            "list_delimiter": "text"
          },
          "idp": {
            "idp_type": "text",
            "domain": "text"
          },
          "hris": {
            "hris_name": "text",
            "hris_type": "text",
            "hris_url": "text",
            "hris_identity_mapping": {
              "mappings": [
                {
                  "destination_datasource_type": "text",
                  "destination_datasource_oaa_app_type": "text",
                  "type": 1,
                  "mode": 1,
                  "transformations": [
                    1
                  ],
                  "custom_value": "text",
                  "property_matchers": [
                    {
                      "source_property": 1,
                      "destination_property": 1,
                      "custom_source_property": "text",
                      "custom_destination_property": "text"
                    }
                  ],
                  "id_matchers": [
                    {
                      "source_id": "text",
                      "destination_id": "text"
                    }
                  ],
                  "destination_datasources": [
                    {
                      "type": "text",
                      "oaa_app_type": "text"
                    }
                  ],
                  "property_match_operator": 1
                }
              ],
              "use_email": true
            },
            "hris_provisioning_source": true
          },
          "cmdb": {
            "cmdb_instance_name": "text",
            "cmdb_instance_type": "text",
            "csc_global_config": {
              "owner_id_column_name": "text",
              "asset_id_column_name": "text",
              "asset_type_column_name": "text",
              "owner_node_type": "text",
              "owner_id_property": "text",
              "asset_connections": [
                {
                  "asset_type_value": "text",
                  "asset_node_type": "text",
                  "asset_property_name": "text"
                }
              ]
            }
          },
          "secret_store": {
            "secret_store_name": "text",
            "secret_store_type": "text",
            "vault_type": "text"
          }
        },
        "secret_references": [
          {
            "id": "text",
            "secret_id": "text",
            "secret_mapping": {
              "type": 1,
              "mapping": "text"
            },
            "vault_id": "text",
            "vault": {
              "id": "text",
              "name": "text",
              "vault_provider": "text",
              "insight_point_id": "text",
              "deleted": true
            }
          }
        ],
        "external_lifecycle_management_type": 1,
        "cmdb_types": [
          "text"
        ],
        "notification_preferences": {
          "enabled": true,
          "subscribed_events": [
            1
          ],
          "notify_integration_owner": true,
          "additional_recipients": [
            "text"
          ],
          "delivery_methods": [
            {
              "type": 1,
              "id": "text"
            }
          ]
        }
      }
    }
    get

    Retrieve all custom (OAA) providers configured in the tenant. Custom providers represent integrations built using the Open Authorization API (OAA), including both Veza-managed connectors and customer-built integrations. Use the filter parameter to narrow results by name, state, or custom_template (e.g., filter=name eq "My App"). Set page_size to control results per page (default varies), and use page_token from the response to retrieve subsequent pages.

    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Query parameters
    filterstringOptional
    order_bystringOptional
    page_sizeinteger · int32Optional

    The maximum number of results to be returned. Fewer results may be returned even when more pages exist.

    page_tokenstringOptional

    The token specifying the specific page of results to retrieve.

    Responses
    200

    OK

    application/json

    Paginated list of custom (OAA) providers.

    idstringOptional

    Unique identifier for the provider instance.

    external_idstringOptional

    External identifier for the provider, typically set by the integration that created it.

    namestringOptional

    Display name of the provider.

    custom_templatestringOptional

    The OAA template type used to create this provider (e.g., "application", "idp").

    custom_templatesstring[]Optional

    List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").

    stateinteger · enumOptional

    Current provider state.

    application_typesstring[]Optional

    Application type classifications for this provider.

    resource_typesstring[]OptionalDeprecated

    Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.

    idp_typesstring[]Optional

    Identity provider type classifications (if this provider represents an IdP).

    file_system_typesstring[]Optional

    File system type classifications (if this provider represents a file system).

    hris_typesstring[]Optional

    HRIS system type classifications (if this provider represents an HR system).

    principal_typesstring[]Optional

    Principal (identity) type classifications for this provider.

    secret_store_typesstring[]Optional
    host_typesstring[]Optional
    schema_definition_jsonstring · bytesOptional
    provisioningbooleanOptional

    Whether provisioning (write-back) operations are enabled for this provider.

    push_typeinteger · enumOptional
    rbac_idstringOptional
    internal_app_namestringOptional
    configuration_jsonstringOptional

    JSON string containing the provider's connection configuration parameters.

    data_plane_idstringOptional

    Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.

    lifecycle_management_stateinteger · enumOptional

    Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.

    team_idstringOptional

    Identifier of the team that owns this provider instance.

    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional

    For external OAA, how to manage lifecycle management requests

    cmdb_typesstring[]Optional
    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    next_page_tokenstringOptional

    Token to retrieve the next page of results. Empty when no more pages exist.

    has_morebooleanOptional

    If true, additional pages of results are available.

    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    get/api/v1/providers/custom
    GET /api/v1/providers/custom HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {
      "values": [
        {
          "id": "text",
          "external_id": "text",
          "name": "text",
          "custom_template": "text",
          "custom_templates": [
            "text"
          ],
          "state": 1,
          "application_types": [
            "text"
          ],
          "idp_types": [
            "text"
          ],
          "file_system_types": [
            "text"
          ],
          "hris_types": [
            "text"
          ],
          "principal_types": [
            "text"
          ],
          "secret_store_types": [
            "text"
          ],
          "host_types": [
            "text"
          ],
          "schema_definition_json": "text",
          "provisioning": true,
          "push_type": 1,
          "rbac_id": "text",
          "internal_app_name": "text",
          "configuration_json": "text",
          "data_plane_id": "text",
          "lifecycle_management_state": 1,
          "team_id": "text",
          "csv_mapping_configuration": {
            "template_type": "text",
            "column_mappings": [
              {
                "column_name": "text",
                "destination_type": "text",
                "destination_property": "text",
                "custom_property": {
                  "name": "text",
                  "type": 1,
                  "lcm_unique_identifier": true
                },
                "as_list": true,
                "template": "text",
                "property_type": 1,
                "is_required": true
              }
            ],
            "application": {
              "application_name": "text",
              "application_type": "text",
              "identity": [
                "text"
              ],
              "resource_type": "text",
              "okta_app_id": "text"
            },
            "advanced": {
              "list_delimiter": "text"
            },
            "idp": {
              "idp_type": "text",
              "domain": "text"
            },
            "hris": {
              "hris_name": "text",
              "hris_type": "text",
              "hris_url": "text",
              "hris_identity_mapping": {
                "mappings": [
                  {
                    "destination_datasource_type": "text",
                    "destination_datasource_oaa_app_type": "text",
                    "type": 1,
                    "mode": 1,
                    "transformations": [
                      1
                    ],
                    "custom_value": "text",
                    "property_matchers": [
                      {
                        "source_property": 1,
                        "destination_property": 1,
                        "custom_source_property": "text",
                        "custom_destination_property": "text"
                      }
                    ],
                    "id_matchers": [
                      {
                        "source_id": "text",
                        "destination_id": "text"
                      }
                    ],
                    "destination_datasources": [
                      {
                        "type": "text",
                        "oaa_app_type": "text"
                      }
                    ],
                    "property_match_operator": 1
                  }
                ],
                "use_email": true
              },
              "hris_provisioning_source": true
            },
            "cmdb": {
              "cmdb_instance_name": "text",
              "cmdb_instance_type": "text",
              "csc_global_config": {
                "owner_id_column_name": "text",
                "asset_id_column_name": "text",
                "asset_type_column_name": "text",
                "owner_node_type": "text",
                "owner_id_property": "text",
                "asset_connections": [
                  {
                    "asset_type_value": "text",
                    "asset_node_type": "text",
                    "asset_property_name": "text"
                  }
                ]
              }
            },
            "secret_store": {
              "secret_store_name": "text",
              "secret_store_type": "text",
              "vault_type": "text"
            }
          },
          "secret_references": [
            {
              "id": "text",
              "secret_id": "text",
              "secret_mapping": {
                "type": 1,
                "mapping": "text"
              },
              "vault_id": "text",
              "vault": {
                "id": "text",
                "name": "text",
                "vault_provider": "text",
                "insight_point_id": "text",
                "deleted": true
              }
            }
          ],
          "external_lifecycle_management_type": 1,
          "cmdb_types": [
            "text"
          ],
          "notification_preferences": {
            "enabled": true,
            "subscribed_events": [
              1
            ],
            "notify_integration_owner": true,
            "additional_recipients": [
              "text"
            ],
            "delivery_methods": [
              {
                "type": 1,
                "id": "text"
              }
            ]
          }
        }
      ],
      "next_page_token": "text",
      "has_more": true
    }
    get
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    Responses
    200

    OK

    application/json
    idstringOptional

    Unique identifier for the provider instance.

    external_idstringOptional

    External identifier for the provider, typically set by the integration that created it.

    namestringOptional

    Display name of the provider.

    custom_templatestringOptional

    The OAA template type used to create this provider (e.g., "application", "idp").

    custom_templatesstring[]Optional

    List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").

    stateinteger · enumOptional

    Current provider state.

    application_typesstring[]Optional

    Application type classifications for this provider.

    resource_typesstring[]OptionalDeprecated

    Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.

    idp_typesstring[]Optional

    Identity provider type classifications (if this provider represents an IdP).

    file_system_typesstring[]Optional

    File system type classifications (if this provider represents a file system).

    hris_typesstring[]Optional

    HRIS system type classifications (if this provider represents an HR system).

    principal_typesstring[]Optional

    Principal (identity) type classifications for this provider.

    secret_store_typesstring[]Optional
    host_typesstring[]Optional
    schema_definition_jsonstring · bytesOptional
    provisioningbooleanOptional

    Whether provisioning (write-back) operations are enabled for this provider.

    push_typeinteger · enumOptional
    rbac_idstringOptional
    internal_app_namestringOptional
    configuration_jsonstringOptional

    JSON string containing the provider's connection configuration parameters.

    data_plane_idstringOptional

    Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.

    lifecycle_management_stateinteger · enumOptional

    Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.

    team_idstringOptional

    Identifier of the team that owns this provider instance.

    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional

    For external OAA, how to manage lifecycle management requests

    cmdb_typesstring[]Optional
    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    get/api/v1/providers/custom/{id}
    GET /api/v1/providers/custom/{id} HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {
      "value": {
        "id": "text",
        "external_id": "text",
        "name": "text",
        "custom_template": "text",
        "custom_templates": [
          "text"
        ],
        "state": 1,
        "application_types": [
          "text"
        ],
        "idp_types": [
          "text"
        ],
        "file_system_types": [
          "text"
        ],
        "hris_types": [
          "text"
        ],
        "principal_types": [
          "text"
        ],
        "secret_store_types": [
          "text"
        ],
        "host_types": [
          "text"
        ],
        "schema_definition_json": "text",
        "provisioning": true,
        "push_type": 1,
        "rbac_id": "text",
        "internal_app_name": "text",
        "configuration_json": "text",
        "data_plane_id": "text",
        "lifecycle_management_state": 1,
        "team_id": "text",
        "csv_mapping_configuration": {
          "template_type": "text",
          "column_mappings": [
            {
              "column_name": "text",
              "destination_type": "text",
              "destination_property": "text",
              "custom_property": {
                "name": "text",
                "type": 1,
                "lcm_unique_identifier": true
              },
              "as_list": true,
              "template": "text",
              "property_type": 1,
              "is_required": true
            }
          ],
          "application": {
            "application_name": "text",
            "application_type": "text",
            "identity": [
              "text"
            ],
            "resource_type": "text",
            "okta_app_id": "text"
          },
          "advanced": {
            "list_delimiter": "text"
          },
          "idp": {
            "idp_type": "text",
            "domain": "text"
          },
          "hris": {
            "hris_name": "text",
            "hris_type": "text",
            "hris_url": "text",
            "hris_identity_mapping": {
              "mappings": [
                {
                  "destination_datasource_type": "text",
                  "destination_datasource_oaa_app_type": "text",
                  "type": 1,
                  "mode": 1,
                  "transformations": [
                    1
                  ],
                  "custom_value": "text",
                  "property_matchers": [
                    {
                      "source_property": 1,
                      "destination_property": 1,
                      "custom_source_property": "text",
                      "custom_destination_property": "text"
                    }
                  ],
                  "id_matchers": [
                    {
                      "source_id": "text",
                      "destination_id": "text"
                    }
                  ],
                  "destination_datasources": [
                    {
                      "type": "text",
                      "oaa_app_type": "text"
                    }
                  ],
                  "property_match_operator": 1
                }
              ],
              "use_email": true
            },
            "hris_provisioning_source": true
          },
          "cmdb": {
            "cmdb_instance_name": "text",
            "cmdb_instance_type": "text",
            "csc_global_config": {
              "owner_id_column_name": "text",
              "asset_id_column_name": "text",
              "asset_type_column_name": "text",
              "owner_node_type": "text",
              "owner_id_property": "text",
              "asset_connections": [
                {
                  "asset_type_value": "text",
                  "asset_node_type": "text",
                  "asset_property_name": "text"
                }
              ]
            }
          },
          "secret_store": {
            "secret_store_name": "text",
            "secret_store_type": "text",
            "vault_type": "text"
          }
        },
        "secret_references": [
          {
            "id": "text",
            "secret_id": "text",
            "secret_mapping": {
              "type": 1,
              "mapping": "text"
            },
            "vault_id": "text",
            "vault": {
              "id": "text",
              "name": "text",
              "vault_provider": "text",
              "insight_point_id": "text",
              "deleted": true
            }
          }
        ],
        "external_lifecycle_management_type": 1,
        "cmdb_types": [
          "text"
        ],
        "notification_preferences": {
          "enabled": true,
          "subscribed_events": [
            1
          ],
          "notify_integration_owner": true,
          "additional_recipients": [
            "text"
          ],
          "delivery_methods": [
            {
              "type": 1,
              "id": "text"
            }
          ]
        }
      }
    }
    patch
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    provider.idstringRequired
    Query parameters
    update_maskstring · field-maskOptional
    Body
    idstringOptional
    configuration_jsonstringOptional
    data_plane_idstringOptional
    provisioningbooleanOptional
    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional
    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    Responses
    200

    OK

    application/json
    idstringOptional

    Unique identifier for the provider instance.

    external_idstringOptional

    External identifier for the provider, typically set by the integration that created it.

    namestringOptional

    Display name of the provider.

    custom_templatestringOptional

    The OAA template type used to create this provider (e.g., "application", "idp").

    custom_templatesstring[]Optional

    List of OAA template types associated with this provider instance (e.g., "application", "idp", "hris").

    stateinteger · enumOptional

    Current provider state.

    application_typesstring[]Optional

    Application type classifications for this provider.

    resource_typesstring[]OptionalDeprecated

    Deprecated. Resource type classifications. Use application_types, idp_types, hris_types, or file_system_types instead.

    idp_typesstring[]Optional

    Identity provider type classifications (if this provider represents an IdP).

    file_system_typesstring[]Optional

    File system type classifications (if this provider represents a file system).

    hris_typesstring[]Optional

    HRIS system type classifications (if this provider represents an HR system).

    principal_typesstring[]Optional

    Principal (identity) type classifications for this provider.

    secret_store_typesstring[]Optional
    host_typesstring[]Optional
    schema_definition_jsonstring · bytesOptional
    provisioningbooleanOptional

    Whether provisioning (write-back) operations are enabled for this provider.

    push_typeinteger · enumOptional
    rbac_idstringOptional
    internal_app_namestringOptional
    configuration_jsonstringOptional

    JSON string containing the provider's connection configuration parameters.

    data_plane_idstringOptional

    Identifier of the data plane that runs this provider's extraction. Empty for cloud-hosted extraction.

    lifecycle_management_stateinteger · enumOptional

    Current lifecycle management state for this provider (enum). Indicates whether provisioning and deprovisioning workflows are active.

    team_idstringOptional

    Identifier of the team that owns this provider instance.

    template_typestringOptional
    column_namestringOptional
    destination_typestringOptional
    destination_propertystringOptional
    namestringOptional
    typeinteger · enumOptional
    lcm_unique_identifierbooleanOptional
    as_listbooleanOptional
    templatestringOptional
    property_typeinteger · enumOptional
    is_requiredbooleanOptional
    application_namestringOptional
    application_typestringOptional
    identitystring[]Optional
    resource_typestringOptional
    okta_app_idstringOptional
    list_delimiterstringOptional
    idp_typestringOptional
    domainstringOptional
    hris_namestringOptional
    hris_typestringOptional
    hris_urlstringOptional
    destination_datasource_typestringOptional
    destination_datasource_oaa_app_typestringOptional
    typeinteger · enumOptional
    modeinteger · enumOptional
    transformationsinteger · enum[]Optional
    custom_valuestringOptional
    source_propertyinteger · enumOptional
    destination_propertyinteger · enumOptional
    custom_source_propertystringOptional
    custom_destination_propertystringOptional
    source_idstringOptional
    destination_idstringOptional
    typestringOptional
    oaa_app_typestringOptional
    property_match_operatorinteger · enumOptional
    use_emailbooleanOptional
    hris_provisioning_sourcebooleanOptional
    cmdb_instance_namestringOptional
    cmdb_instance_typestringOptional
    owner_id_column_namestringOptional
    asset_id_column_namestringOptional
    asset_type_column_namestringOptional
    owner_node_typestringOptional
    owner_id_propertystringOptional
    asset_type_valuestringOptional
    asset_node_typestringOptional
    asset_property_namestringOptional
    secret_store_namestringOptional

    Name of the secret store instance, e.g. the customer's Thales CipherTrust deployment.

    secret_store_typestringOptional

    Vendor of the secret store, e.g. "thales_ciphertrust". One per datasource.

    vault_typestringOptional

    Default vault type applied to vaults that do not map a vault_type column.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    external_lifecycle_management_typeinteger · enumOptional

    For external OAA, how to manage lifecycle management requests

    cmdb_typesstring[]Optional
    enabledbooleanOptional
    subscribed_eventsinteger · enum[]Optional
    notify_integration_ownerbooleanOptional
    additional_recipientsstring[]Optional
    typeinteger · enumOptional
    idstringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    patch/api/v1/providers/custom/{provider.id}
    PATCH /api/v1/providers/custom/{provider.id} HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 1929
    
    {
      "id": "text",
      "configuration_json": "text",
      "data_plane_id": "text",
      "provisioning": true,
      "csv_mapping_configuration": {
        "template_type": "text",
        "column_mappings": [
          {
            "column_name": "text",
            "destination_type": "text",
            "destination_property": "text",
            "custom_property": {
              "name": "text",
              "type": 1,
              "lcm_unique_identifier": true
            },
            "as_list": true,
            "template": "text",
            "property_type": 1,
            "is_required": true
          }
        ],
        "application": {
          "application_name": "text",
          "application_type": "text",
          "identity": [
            "text"
          ],
          "resource_type": "text",
          "okta_app_id": "text"
        },
        "advanced": {
          "list_delimiter": "text"
        },
        "idp": {
          "idp_type": "text",
          "domain": "text"
        },
        "hris": {
          "hris_name": "text",
          "hris_type": "text",
          "hris_url": "text",
          "hris_identity_mapping": {
            "mappings": [
              {
                "destination_datasource_type": "text",
                "destination_datasource_oaa_app_type": "text",
                "type": 1,
                "mode": 1,
                "transformations": [
                  1
                ],
                "custom_value": "text",
                "property_matchers": [
                  {
                    "source_property": 1,
                    "destination_property": 1,
                    "custom_source_property": "text",
                    "custom_destination_property": "text"
                  }
                ],
                "id_matchers": [
                  {
                    "source_id": "text",
                    "destination_id": "text"
                  }
                ],
                "destination_datasources": [
                  {
                    "type": "text",
                    "oaa_app_type": "text"
                  }
                ],
                "property_match_operator": 1
              }
            ],
            "use_email": true
          },
          "hris_provisioning_source": true
        },
        "cmdb": {
          "cmdb_instance_name": "text",
          "cmdb_instance_type": "text",
          "csc_global_config": {
            "owner_id_column_name": "text",
            "asset_id_column_name": "text",
            "asset_type_column_name": "text",
            "owner_node_type": "text",
            "owner_id_property": "text",
            "asset_connections": [
              {
                "asset_type_value": "text",
                "asset_node_type": "text",
                "asset_property_name": "text"
              }
            ]
          }
        },
        "secret_store": {
          "secret_store_name": "text",
          "secret_store_type": "text",
          "vault_type": "text"
        }
      },
      "secret_references": [
        {
          "secret_id": "text",
          "secret_mapping": {
            "type": 1,
            "mapping": "text"
          },
          "vault_id": "text"
        }
      ],
      "external_lifecycle_management_type": 1,
      "notification_preferences": {
        "enabled": true,
        "subscribed_events": [
          1
        ],
        "notify_integration_owner": true,
        "additional_recipients": [
          "text"
        ],
        "delivery_methods": [
          {
            "type": 1,
            "id": "text"
          }
        ]
      }
    }
    {
      "value": {
        "id": "text",
        "external_id": "text",
        "name": "text",
        "custom_template": "text",
        "custom_templates": [
          "text"
        ],
        "state": 1,
        "application_types": [
          "text"
        ],
        "idp_types": [
          "text"
        ],
        "file_system_types": [
          "text"
        ],
        "hris_types": [
          "text"
        ],
        "principal_types": [
          "text"
        ],
        "secret_store_types": [
          "text"
        ],
        "host_types": [
          "text"
        ],
        "schema_definition_json": "text",
        "provisioning": true,
        "push_type": 1,
        "rbac_id": "text",
        "internal_app_name": "text",
        "configuration_json": "text",
        "data_plane_id": "text",
        "lifecycle_management_state": 1,
        "team_id": "text",
        "csv_mapping_configuration": {
          "template_type": "text",
          "column_mappings": [
            {
              "column_name": "text",
              "destination_type": "text",
              "destination_property": "text",
              "custom_property": {
                "name": "text",
                "type": 1,
                "lcm_unique_identifier": true
              },
              "as_list": true,
              "template": "text",
              "property_type": 1,
              "is_required": true
            }
          ],
          "application": {
            "application_name": "text",
            "application_type": "text",
            "identity": [
              "text"
            ],
            "resource_type": "text",
            "okta_app_id": "text"
          },
          "advanced": {
            "list_delimiter": "text"
          },
          "idp": {
            "idp_type": "text",
            "domain": "text"
          },
          "hris": {
            "hris_name": "text",
            "hris_type": "text",
            "hris_url": "text",
            "hris_identity_mapping": {
              "mappings": [
                {
                  "destination_datasource_type": "text",
                  "destination_datasource_oaa_app_type": "text",
                  "type": 1,
                  "mode": 1,
                  "transformations": [
                    1
                  ],
                  "custom_value": "text",
                  "property_matchers": [
                    {
                      "source_property": 1,
                      "destination_property": 1,
                      "custom_source_property": "text",
                      "custom_destination_property": "text"
                    }
                  ],
                  "id_matchers": [
                    {
                      "source_id": "text",
                      "destination_id": "text"
                    }
                  ],
                  "destination_datasources": [
                    {
                      "type": "text",
                      "oaa_app_type": "text"
                    }
                  ],
                  "property_match_operator": 1
                }
              ],
              "use_email": true
            },
            "hris_provisioning_source": true
          },
          "cmdb": {
            "cmdb_instance_name": "text",
            "cmdb_instance_type": "text",
            "csc_global_config": {
              "owner_id_column_name": "text",
              "asset_id_column_name": "text",
              "asset_type_column_name": "text",
              "owner_node_type": "text",
              "owner_id_property": "text",
              "asset_connections": [
                {
                  "asset_type_value": "text",
                  "asset_node_type": "text",
                  "asset_property_name": "text"
                }
              ]
            }
          },
          "secret_store": {
            "secret_store_name": "text",
            "secret_store_type": "text",
            "vault_type": "text"
          }
        },
        "secret_references": [
          {
            "id": "text",
            "secret_id": "text",
            "secret_mapping": {
              "type": 1,
              "mapping": "text"
            },
            "vault_id": "text",
            "vault": {
              "id": "text",
              "name": "text",
              "vault_provider": "text",
              "insight_point_id": "text",
              "deleted": true
            }
          }
        ],
        "external_lifecycle_management_type": 1,
        "cmdb_types": [
          "text"
        ],
        "notification_preferences": {
          "enabled": true,
          "subscribed_events": [
            1
          ],
          "notify_integration_owner": true,
          "additional_recipients": [
            "text"
          ],
          "delivery_methods": [
            {
              "type": 1,
              "id": "text"
            }
          ]
        }
      }
    }
    delete
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    Responses
    200

    OK

    application/json
    object · DeleteCustomProviderResponseOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    delete/api/v1/providers/custom/{id}
    DELETE /api/v1/providers/custom/{id} HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {}
    get
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    Query parameters
    filterstringOptional
    order_bystringOptional
    page_sizeinteger · int32Optional

    The maximum number of results to be returned. Fewer results may be returned even when more pages exist.

    page_tokenstringOptional

    The token specifying the specific page of results to retrieve.

    Responses
    200

    OK

    application/json
    idstringOptional
    namestringOptional
    datasource_typeinteger · enumOptional
    agent_typeinteger · enumOptional
    statusinteger · enumOptional

    Status is the status of current ingestion. See PreviousStatus for the status of the previous ingestion.

    previous_statusinteger · enumOptional

    PreviousStatus is a SUCCESS, ERROR or one of the specific error statuses unless the initial ingestion is in progress in which case it is one of EXTRACTION_PENDING, EXTRACTION_IN_PROGRESS, PARSE_PENDING or PARSE_IN_PROGRESS.

    provider_idstringOptional
    pathstringOptional
    external_idstringOptional
    stateinteger · enumOptional
    effective_stateinteger · enumOptional
    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    created_atstringOptional
    updated_atstringOptional
    synced_atstringOptionalDeprecated

    SyncedAt timestamp is deprecated in favor of SyncStart, SyncEnd, SyncStartSuccess, SyncEndSuccess

    parsed_atstringOptionalDeprecated

    ParsedAt records ingestion time of the latest ingestion attempt.

    parsed_at_successstring · date-timeOptionalDeprecated

    ParsedAtSuccess records ingestion time of the latest successful ingestion. See SyncStartSuccess and SyncEndSuccess for data extraction timestamps.

    pushed_atstring · date-timeOptional

    PushedAt is set when a custom datasource payload is pushed.

    sync_startstring · date-timeOptional

    SyncStart records extraction start time of the latest extraction attempt.

    sync_endstring · date-timeOptional

    SyncEnd records extraction end time of the latest extraction attempt.

    sync_start_successstring · date-timeOptional

    SyncStartSuccess records extraction start time of the latest successful ingestion.

    sync_end_successstring · date-timeOptional

    SyncEndSuccess records extraction end time of the latest successful ingestion.

    reasoninteger · enumOptional
    messagestringOptional
    resolutionstringOptional
    original_messagestringOptional
    stepinteger · enumOptional
    agent_categoryinteger · enumOptional
    provider_typeinteger · enumOptional
    rbac_idstringRead-onlyOptional

    RBAC ID for the provider as it controls access control for the datasource.

    parse_startstringOptional

    ParseStart records parse start time of the latest parse attempt.

    parse_start_successstring · date-timeOptional

    ParseStartSuccess records parse start time of the latest successful parse.

    parse_start_non_metadatastring · date-timeOptional

    ParseStartNonMetadata records parse start time of the latest non-metadata parse attempt.

    parse_start_success_non_metadatastring · date-timeOptional

    ParseStartSuccessNonMetadata records parse start time of the latest successful non-metadata parse.

    parse_end_non_metadatastring · date-timeOptional

    ParseEndNonMetadata records parse end time of the latest non-metadata parse attempt.

    retriesinteger · int32Optional

    Retries is the number of parse retries for the current ingestion.

    skipped_parsesinteger · int32Optional

    SkippedParses is the number of skipped parses for the current ingestion.

    parse_endstringOptional

    ParseEnd records parse end time of the latest parse attempt.

    parse_end_successstring · date-timeOptional

    ParseEndSuccess records parse end time of the latest successful parse.

    parse_end_success_non_metadatastring · date-timeOptional

    ParseEndSuccessNonMetadata records parse end time of the latest successful non-metadata parse.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    next_page_tokenstringOptional

    The pagination token to retrieve the next page of results.

    has_morebooleanOptional

    If true, more results are available.

    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    get/api/v1/providers/custom/{id}/datasources
    GET /api/v1/providers/custom/{id}/datasources HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {
      "values": [
        {
          "id": "text",
          "name": "text",
          "datasource_type": 1,
          "agent_type": 1,
          "status": 1,
          "previous_status": 1,
          "provider_id": "text",
          "path": "text",
          "external_id": "text",
          "state": 1,
          "effective_state": 1,
          "datasource_config": {
            "@type": "text",
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "created_at": "text",
          "updated_at": "text",
          "pushed_at": "2026-01-01T00:00:00.000Z",
          "sync_start": "2026-01-01T00:00:00.000Z",
          "sync_end": "2026-01-01T00:00:00.000Z",
          "sync_start_success": "2026-01-01T00:00:00.000Z",
          "sync_end_success": "2026-01-01T00:00:00.000Z",
          "error": {
            "reason": 1,
            "message": "text",
            "resolution": "text",
            "original_message": "text",
            "step": 1
          },
          "agent_category": 1,
          "provider_type": 1,
          "rbac_id": "text",
          "parse_start": "text",
          "parse_start_success": "2026-01-01T00:00:00.000Z",
          "parse_start_non_metadata": "2026-01-01T00:00:00.000Z",
          "parse_start_success_non_metadata": "2026-01-01T00:00:00.000Z",
          "parse_end_non_metadata": "2026-01-01T00:00:00.000Z",
          "retries": 1,
          "skipped_parses": 1,
          "parse_end": "text",
          "parse_end_success": "2026-01-01T00:00:00.000Z",
          "parse_end_success_non_metadata": "2026-01-01T00:00:00.000Z",
          "secret_references": [
            {
              "id": "text",
              "secret_id": "text",
              "secret_mapping": {
                "type": 1,
                "mapping": "text"
              },
              "vault_id": "text",
              "vault": {
                "id": "text",
                "name": "text",
                "vault_provider": "text",
                "insight_point_id": "text",
                "deleted": true
              }
            }
          ]
        }
      ],
      "next_page_token": "text",
      "has_more": true
    }
    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    Body
    idstringOptional
    namestringOptional
    custom_templatestringOptional
    Responses
    200

    OK

    application/json
    idstringOptional
    namestringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom/{id}/datasources
    POST /api/v1/providers/custom/{id}/datasources HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 52
    
    {
      "id": "text",
      "name": "text",
      "custom_template": "text"
    }
    {
      "value": {
        "id": "text",
        "name": "text"
      }
    }
    get
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    data_source_idstringRequired
    Responses
    200

    OK

    application/json
    idstringOptional
    namestringOptional
    datasource_typeinteger · enumOptional
    agent_typeinteger · enumOptional
    statusinteger · enumOptional

    Status is the status of current ingestion. See PreviousStatus for the status of the previous ingestion.

    previous_statusinteger · enumOptional

    PreviousStatus is a SUCCESS, ERROR or one of the specific error statuses unless the initial ingestion is in progress in which case it is one of EXTRACTION_PENDING, EXTRACTION_IN_PROGRESS, PARSE_PENDING or PARSE_IN_PROGRESS.

    provider_idstringOptional
    pathstringOptional
    external_idstringOptional
    stateinteger · enumOptional
    effective_stateinteger · enumOptional
    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    created_atstringOptional
    updated_atstringOptional
    synced_atstringOptionalDeprecated

    SyncedAt timestamp is deprecated in favor of SyncStart, SyncEnd, SyncStartSuccess, SyncEndSuccess

    parsed_atstringOptionalDeprecated

    ParsedAt records ingestion time of the latest ingestion attempt.

    parsed_at_successstring · date-timeOptionalDeprecated

    ParsedAtSuccess records ingestion time of the latest successful ingestion. See SyncStartSuccess and SyncEndSuccess for data extraction timestamps.

    pushed_atstring · date-timeOptional

    PushedAt is set when a custom datasource payload is pushed.

    sync_startstring · date-timeOptional

    SyncStart records extraction start time of the latest extraction attempt.

    sync_endstring · date-timeOptional

    SyncEnd records extraction end time of the latest extraction attempt.

    sync_start_successstring · date-timeOptional

    SyncStartSuccess records extraction start time of the latest successful ingestion.

    sync_end_successstring · date-timeOptional

    SyncEndSuccess records extraction end time of the latest successful ingestion.

    reasoninteger · enumOptional
    messagestringOptional
    resolutionstringOptional
    original_messagestringOptional
    stepinteger · enumOptional
    agent_categoryinteger · enumOptional
    provider_typeinteger · enumOptional
    rbac_idstringRead-onlyOptional

    RBAC ID for the provider as it controls access control for the datasource.

    parse_startstringOptional

    ParseStart records parse start time of the latest parse attempt.

    parse_start_successstring · date-timeOptional

    ParseStartSuccess records parse start time of the latest successful parse.

    parse_start_non_metadatastring · date-timeOptional

    ParseStartNonMetadata records parse start time of the latest non-metadata parse attempt.

    parse_start_success_non_metadatastring · date-timeOptional

    ParseStartSuccessNonMetadata records parse start time of the latest successful non-metadata parse.

    parse_end_non_metadatastring · date-timeOptional

    ParseEndNonMetadata records parse end time of the latest non-metadata parse attempt.

    retriesinteger · int32Optional

    Retries is the number of parse retries for the current ingestion.

    skipped_parsesinteger · int32Optional

    SkippedParses is the number of skipped parses for the current ingestion.

    parse_endstringOptional

    ParseEnd records parse end time of the latest parse attempt.

    parse_end_successstring · date-timeOptional

    ParseEndSuccess records parse end time of the latest successful parse.

    parse_end_success_non_metadatastring · date-timeOptional

    ParseEndSuccessNonMetadata records parse end time of the latest successful non-metadata parse.

    idstringRead-onlyOptional
    secret_idstringOptional
    typeinteger · enumOptional
    mappingstringOptional
    vault_idstringOptional
    idstringRead-onlyOptional
    namestringOptional

    Must be unique within an insight point

    vault_providerstringOptional

    Provider type: "azure_key_vault", "aws_secrets_manager", etc.

    insight_point_idstringOptional

    Owning insight point ID, or "internal" for control plane vaults

    deletedbooleanOptional

    Soft-deleted flag for external vaults; restored by re-registering (internal vaults are hard-deleted)

    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    get/api/v1/providers/custom/{id}/datasources/{data_source_id}
    GET /api/v1/providers/custom/{id}/datasources/{data_source_id} HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {
      "value": {
        "id": "text",
        "name": "text",
        "datasource_type": 1,
        "agent_type": 1,
        "status": 1,
        "previous_status": 1,
        "provider_id": "text",
        "path": "text",
        "external_id": "text",
        "state": 1,
        "effective_state": 1,
        "datasource_config": {
          "@type": "text",
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "created_at": "text",
        "updated_at": "text",
        "pushed_at": "2026-01-01T00:00:00.000Z",
        "sync_start": "2026-01-01T00:00:00.000Z",
        "sync_end": "2026-01-01T00:00:00.000Z",
        "sync_start_success": "2026-01-01T00:00:00.000Z",
        "sync_end_success": "2026-01-01T00:00:00.000Z",
        "error": {
          "reason": 1,
          "message": "text",
          "resolution": "text",
          "original_message": "text",
          "step": 1
        },
        "agent_category": 1,
        "provider_type": 1,
        "rbac_id": "text",
        "parse_start": "text",
        "parse_start_success": "2026-01-01T00:00:00.000Z",
        "parse_start_non_metadata": "2026-01-01T00:00:00.000Z",
        "parse_start_success_non_metadata": "2026-01-01T00:00:00.000Z",
        "parse_end_non_metadata": "2026-01-01T00:00:00.000Z",
        "retries": 1,
        "skipped_parses": 1,
        "parse_end": "text",
        "parse_end_success": "2026-01-01T00:00:00.000Z",
        "parse_end_success_non_metadata": "2026-01-01T00:00:00.000Z",
        "secret_references": [
          {
            "id": "text",
            "secret_id": "text",
            "secret_mapping": {
              "type": 1,
              "mapping": "text"
            },
            "vault_id": "text",
            "vault": {
              "id": "text",
              "name": "text",
              "vault_provider": "text",
              "insight_point_id": "text",
              "deleted": true
            }
          }
        ]
      }
    }
    delete
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    data_source_idstringRequired
    Responses
    200

    OK

    application/json
    object · DeleteCustomProviderDatasourceResponseOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    delete/api/v1/providers/custom/{id}/datasources/{data_source_id}
    DELETE /api/v1/providers/custom/{id}/datasources/{data_source_id} HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {}
    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    data_source_idstringRequired
    Body
    idstringOptional
    data_source_idstringOptional
    json_datastringOptional
    compression_typeinteger · enumOptional
    priority_pushbooleanOptional
    Responses
    200

    OK

    application/json
    messagestringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom/{id}/datasources/{data_source_id}:push
    POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 98
    
    {
      "id": "text",
      "data_source_id": "text",
      "json_data": "text",
      "compression_type": 1,
      "priority_push": true
    }
    {
      "warnings": [
        {
          "message": "text"
        }
      ]
    }
    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    data_source_idstringRequired
    Body
    idstringOptional
    data_source_idstringOptional
    csv_datastringOptional
    namestringOptional
    typestringOptional
    compression_typeinteger · enumOptional
    priority_pushbooleanOptional
    Responses
    200

    OK

    application/json
    messagestringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom/{id}/datasources/{data_source_id}:push_csv
    POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push_csv HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 125
    
    {
      "id": "text",
      "data_source_id": "text",
      "csv_data": "text",
      "name": "text",
      "type": "text",
      "compression_type": 1,
      "priority_push": true
    }
    {
      "warnings": [
        {
          "message": "text"
        }
      ]
    }
    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    data_source_idstringRequired
    Body
    idstringOptional
    data_source_idstringOptional
    json_datastringOptional
    compression_typeinteger · enumOptional
    priority_pushbooleanOptional
    Responses
    200

    OK

    application/json
    messagestringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom/{id}/datasources/{data_source_id}:push
    POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 98
    
    {
      "id": "text",
      "data_source_id": "text",
      "json_data": "text",
      "compression_type": 1,
      "priority_push": true
    }
    {
      "warnings": [
        {
          "message": "text"
        }
      ]
    }
    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    data_source_idstringRequired
    Body
    idstringOptional
    data_source_idstringOptional
    csv_datastringOptional
    namestringOptional
    typestringOptional
    compression_typeinteger · enumOptional
    priority_pushbooleanOptional
    Responses
    200

    OK

    application/json
    messagestringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom/{id}/datasources/{data_source_id}:push_csv
    POST /api/v1/providers/custom/{id}/datasources/{data_source_id}:push_csv HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 125
    
    {
      "id": "text",
      "data_source_id": "text",
      "csv_data": "text",
      "name": "text",
      "type": "text",
      "compression_type": 1,
      "priority_push": true
    }
    {
      "warnings": [
        {
          "message": "text"
        }
      ]
    }
    post
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    Body
    idstringOptional
    icon_base64stringOptional
    Responses
    200

    OK

    application/json
    object · CreateCustomProviderIconResponseOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    post/api/v1/providers/custom/{id}:icon
    POST /api/v1/providers/custom/{id}:icon HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Content-Type: application/json
    Accept: */*
    Content-Length: 34
    
    {
      "id": "text",
      "icon_base64": "text"
    }
    {}
    get
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    Responses
    200

    OK

    application/json
    mime_typestringOptional
    icon_base64stringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    get/api/v1/providers/custom/{id}:icon
    GET /api/v1/providers/custom/{id}:icon HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {
      "mime_type": "text",
      "icon_base64": "text"
    }
    get
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Query parameters
    app_or_idp_typestringOptionalDeprecated
    custom_schema_typestringOptional
    node_typestringOptional
    Responses
    200

    OK

    application/json
    mime_typestringOptional
    icon_base64stringOptional
    provider_idstringOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    get/api/v1/providers/custom:icon
    GET /api/v1/providers/custom:icon HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {
      "mime_type": "text",
      "icon_base64": "text",
      "provider_id": "text"
    }
    delete
    Authorizations
    AuthorizationstringRequired

    Veza API key for authentication. Generate keys in Administration > API Keys.

    Path parameters
    idstringRequired
    Responses
    200

    OK

    application/json
    object · DeleteCustomProviderIconResponseOptional
    default

    Default error response

    application/json

    The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

    codeinteger · int32Optional

    The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

    messagestringOptional

    A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

    @typestringOptional

    The type of the serialized message.

    Other propertiesanyOptional
    delete/api/v1/providers/custom/{id}:icon
    DELETE /api/v1/providers/custom/{id}:icon HTTP/1.1
    Host: your-tenant.vezacloud.com
    Authorization: Bearer YOUR_SECRET_TOKEN
    Accept: */*
    
    {}
    SDK operations

    List custom providers

    Sample IdP from CSV file

    The most common OAA use case is modeling local identities, data sources, and permissions within an application containing sensitive information such as a database, ticket desk, or SCM platform. This sample app uses the CustomApplication class to create an OAA payload for a typical application that includes users, groups, roles and resources.

    Customers that implement a custom Identity Provider (or one that doesn't have a native Veza integration) can use the OAA Custom IdP template to describe federated users and groups. This sample app generates a custom payload containing users, groups, and identity metadata, using the CustomIdPProvider class.

    The example also demonstrates OAA support for AWS role entitlements, for scenarios where users can assume AWS roles in ways that can't be discovered by Veza's native AWS integration.

    Sample app for importing Custom Identity Provider users from a CSV file.

    This example can be used as a simple starting point for an OAA data source importer. Demonstrates use of CustomIdPProvider to create IdP users and assign properties using an input file with with the column headings:

    identity,name,full_name,is_active,is_guest,manager_id

    export OAA_TOKEN="xxxxxxx"
    export VEZA_URL="https://myveza.vezacloud.com"
    ./sample-app.py
    Veza-supported connectors
    Sample Application
    Sample Identity Provider

    Sample Application

    sample-app.py

    Sample Identity Provider

    sample-idp.py

    Sample IdP from CSV input

    IdPImportCSV.py

    Custom HRIS Provider

    OAA Template for Human Resources Information Systems

    Overview

    Use this Open Authorization API template to publish employee metadata for Human Resources Information Systems (HRIS) platforms, typically used by organizations as a single source of truth for employee information.

    Unlike an Identity Provider, HR platforms typically do not provide access to other systems. Employee profiles within an HRIS platform are instead used to store important details such as employment status, who individuals report to, department, and country. Veza can use this metadata to:

    • Trigger Lifecycle Management events when there is a change in the integrated HRIS data source.

    • Correlate employees in the HRIS system with identities in your identity provider (IdP).

    • Enrich Access Reviews with details about linked HRIS employees for users under review.

    The template supports:

    • A top-level System entity representing the HRIS tenant, organization, or account.

    • Employee entities representing current and inactive workers

    • Group entities representing teams, departments, cost centers, or other units to which users are assigned.

    To enable this payload format, specify the hris custom template when with the API.

    The HRIS template supports . After specifying a custom property definition in the payload, you can assign additional attributes to entities. These enable attribute filters for searches and access reviews in Veza, and enrich results with entity metadata unique to the source system or your organization.

    Veza maps HRIS employees to identities from integrated Identity Providers (IdPs) such as Okta by matching the idp_id, email, or employee_number value in the HRIS payload with the IdP entity's Name, Principal Name, or Identity. The matching process checks these fields in the following sequence:

    1. idp_id

    2. email

    3. employee_number

    If the idp_id is unset, Veza uses the email field for matching. If the email field is also absent, the employee_number is used. Veza issues a warning if no matching entity is found.

    Veza compares only that one resolved value, and the comparison ignores case but is otherwise exact. An employee_number therefore correlates only when the IdP login, principal name, or email address is itself that number: Veza does not compare it to an Employee ID attribute on the IdP user. For the attributes Veza compares for each provider, see . To correlate on an attribute outside that set, add an identity_mapping_configuration to the HRIS system, or configure a mapping on the identity provider integration. See .

    The account/tenant/etc. that contains the HR information.

    Property
    Attribute Name
    Type
    Required
    Unique
    Description

    Used to represent any person who has been employed by a company.

    Property
    Attribute Name
    Type
    Required
    Unique
    Description

    Used to represent any subset of employees, such as PayGroup or Team. Employees can be in multiple Groups.

    Property
    Attribute Name
    Type
    Required
    Unique
    Description

    Connector Requirements

    Choosing your development environment and deploying an OAA connector

    The Open Authorization API enables developers to push metadata to the Veza Access Graph using a standard JSON schema. To automate this process, you will need a way to periodically query the data source you want to integrate, populate the schema, and publish the populated template payload to your Veza instance using API calls.

    You can interact with the Veza API from your client or language of choice. OAA connectors can (and have) been developed in a variety of languages. The only requirements are the ability to:

    • query the source application (or , or another method) to collect identity, resource, and authorization metadata

    • assemble a dict or similar data structure and convert to JSON

  • make REST API calls to publish the payload

  • Veza provides a Python SDK oaaclient. This package provides functions for generating and submitting the JSON payload. The Veza developed community connectors use this toolkit, along with all integrations built by active customer developers.

    You can run OAAClient as a manual CLI tool for trial purposes, but should automate any long-running OAA implementation. A DevOps or SecOps team is typically responsible for establishing continuous integration of a Veza connector.

    Customers are responsible for running their own connectors. The frequency your app must run will depend on use case, ranging from daily to hourly. Veza typically refreshes metadata for built-in integrations on an hourly basis. However, you can decide to publish OAA payloads on any schedule.

    At a minimum, a deployed OAA connector should be able to:

    • Parse the data source and push an updated payload on a schedule

    • Securely handle secrets such as API keys

    Teams should follow their preferred processes and use familiar or existing platforms. Some options include:

    • AWS Lambda function

    • Docker/k8s-based container

    • cron task

    • GitHub action

    Veza expects the default push to contain a full payload. This will overwrite all information in the updated data source.

    During development, it is usually most efficient to design your parser for a full discovery. It will be easiest to design the connector to assemble and push the full payload, and use the same code to publish updates.

    OAA does support incremental update as an optional behavior–if your custom data source or identity provider provides a way to get individual changes over time, you could design your connector to parse only new or changed entities, and push updates individually (perhaps in response to detected changes). However, this approach will be more complicated. A full parse-and-push will be more efficient, unless there's a method to query the provider for differences since the last push.

    To use incremental updates:

    • Set the is_incremental flag in the payload to true

    • Add an add, modify or delete operation to all entities

    read a data file

    Deploying your connector

    Choosing between full push and incremental updates

    idp_providers

    String list

    N

    N

    List of destination IdP provider types to connect this system to (e.g. okta, azure_ad).

    Identity Mapping Configuration

    identity_mapping_configuration

    Object

    N

    N

    Configuration for mapping employees to identities in external data sources.

    Company

    company

    String

    N

    N

    The company (or subsidiary) the employee works for.

    First Name

    first_name

    String

    N

    N

    The employee's first name.

    Last Name

    last_name

    String

    N

    N

    The employee's last name.

    Preferred Name

    preferred_name

    String

    N

    N

    The employee's preferred first name.

    Display Full Name

    display_full_name

    String

    N

    N

    The employee's full name, to use for display purposes. If a preferred first name is available, the full name will include the preferred first name.

    Canonical Name

    canonical_name

    String

    N

    N

    The employee's canonical name.

    Username

    username

    String

    N

    N

    The employee's username that appears in the integration UI.

    Email

    email

    String

    N

    Y

    The employee's work email.

    IDP ID

    idp_id

    String

    N

    N

    The ID for this employee on the destination IDP provider used to automatically connect to it, if not supplied email is used.

    Personal Email

    personal_email

    String

    N

    N

    The employee's personal email.

    Home Location

    home_location

    String

    N

    N

    The employee's home location.

    Work Location

    work_location

    String

    N

    N

    The employee's work location.

    Cost Center

    cost_center

    EntityRef

    N

    N

    Reference to the group representing the cost center the employee is in (e.g. {"id": "cost-center-001"}).

    Department

    department

    EntityRef

    N

    N

    Reference to the group representing the department the employee is in (e.g. {"id": "engineering"}).

    Managers

    managers

    EntityRef list

    N

    N

    References to the employee's managers (e.g. [{"id": "987654"}]).

    Groups

    groups

    EntityRef list

    N

    N

    References to the groups this employee is in (e.g. [{"id": "all_employees"}]).

    Employment Status

    employment_status

    String

    N

    N

    The employment status of the employee. Possible values include - ACTIVE, PENDING, INACTIVE.

    Is Active

    is_active

    Boolean

    N

    N

    If the employee is active or not.

    Start Date

    start_date

    Timestamp

    N

    N

    The date that the employee started working. If an employee was rehired, the most recent start date will be returned.

    Termination Date

    termination_date

    Timestamp

    N

    N

    The employee's termination date.

    Job Title

    job_title

    String

    N

    N

    The title of the employee.

    Employment Types

    employment_types

    String list

    N

    N

    The employee's type of employment. Possible values include - FULL_TIME, PART_TIME, INTERN, CONTRACTOR, FREELANCE.

    Primary Time Zone

    primary_time_zone

    String

    N

    N

    The time zone which the employee primarily lives.

    parent

    EntityRef

    N

    N

    Reference to the parent group (e.g. {"id": "parent-group-id"}).

    URL

    url

    String

    N

    N

    The url for this HRIS system.

    Employee Number

    employee_number

    String

    N

    Y

    Group Type

    group_type

    String

    Y

    N

    The type of group, possible values include - TEAM, DEPARTMENT, COST_CENTER, BUSINESS_UNIT, GROUP. This is intended as to not have each type as their own nodes.

    HRIS template example

    Custom properties

    Identity mappings

    Custom HRIS System

    Custom HRIS Employee

    Custom HRIS Group

    creating an OAA provider
    custom properties
    Automatic Identity Matching
    Custom Identity Mappings

    IDP Providers

    The employee's number that appears in the third-party integration.

    Parent

    {
      "name": "HRIS Example",
      "hris_type": "HR Platform",
      "custom_property_definition": {
        "system_properties": {},
        "employee_properties": {
          "job_level": "STRING"
        },
        "group_properties": {}
      },
      "system": {
        "id": "7D8A21AE-6650-4357-842B-3FCEC8F29195",
        "name": "HRIS Example",
        "url": "https://hris.example.com",
      },
      "employees": [
        {
          "id": "123456",
          "name": "jdoe",
          "employee_number": "E123456",
          "first_name": "John",
          "last_name": "Doe",
          "canonical_name": "Doe, John",
          "email": "jdoe@example.com",
          "home_location": "Anytown, CA",
          "work_location": "San Francisco, CA",
          "employment_status": "HIRED",
          "start_date": "2022-05-22T00:00:00Z",
          "job_title": "Software Developer",
          "employment_types": [
            "FULL_TIME"
          ],
          "custom_properties": {
            "job_level": "L3"
          },
          "is_active": true,
          "groups": [
            {
              "id": "all_employees"
            }
          ],
          "managers": [
            {
              "id": "987654"
            }
          ],
          "department": {
            "id": "engineering"
          }
        },
        {
          "id": "987654",
          "name": "jane.doe",
          "employee_number": "E987654",
          "first_name": "Jane",
          "last_name": "Doe",
          "canonical_name": "Doe, Jane",
          "email": "jane.doe@example.com",
          "home_location": "Anytown, CA",
          "work_location": "San Francisco, CA",
          "employment_status": "HIRED",
          "start_date": "2021-03-13T00:00:00Z",
          "job_title": "Software Developer",
          "employment_types": [
            "FULL_TIME"
          ],
          "custom_properties": {
            "job_level": "M2"
          },
          "is_active": true,
          "groups": [
            {
              "id": "all_employees"
            }
          ],
          "department": {
            "id": "engineering"
          }
        }
      ],
      "groups": [
        {
          "id": "all_employees",
          "name": "All Employees",
          "group_type": "Employee Group"
        },
        {
          "id": "engineering",
          "name": "Engineering",
          "group_type": "Department"
        }
      ]
    }
    {
      "name": "BambooHR",
      "hris_type": "BambooHR",
      "custom_property_definition": {
        "employee_properties": {
          "division": "STRING",
          "office_extension": "STRING"
        },
        "group_properties": {
          "headquarters_location": "STRING"
        }
      },
      "system": {
        "name": "BambooHR",
        "id": "BambooHR",
        "url": "https://vezai.bamboohr.com",
        "idp_providers": ["okta"]
      },
      "employees": [
        {
          "name": "Charlotte Abbott",
          "id": "1",
          "custom_properties": {
            "division": "North America",
            "office_extension": "1234"
          },
          "employee_number": "1",
          "email": "cabbott@efficientoffice.com",
          "work_location": "Lindon, Utah",
          "job_title": "Sr. HR Administrator"
        },
        {
          "name": "Cheryl Barnet",
          "id": "10",
          "custom_properties": {
            "division": "North America",
            "office_extension": "5678"
          },
          "employee_number": "10",
          "email": "cbarnet@efficientoffice.com",
          "work_location": "Lindon, Utah",
          "job_title": "VP of Customer Success"
        }
      ],
      "groups": [
        {
          "name": "North America-Human Resources",
          "id": "North America-Human Resources",
          "group_type": "Department",
          "custom_properties": {
            "headquarters_location": "Lindon, Utah"
          }
        }
      ]
    }
    #!env python3
    """Example of using `oaaclient` to import users from a CSV file.
    
    Reads user properties from the input file, populates an OAA payload,
    and creates a new OAA identity provider containing the imported users.
    
    Expected CSV headers are `identity,name,full_name,is_active,is_guest,manager_id`
    Can be updated to match custom column headings or apply custom properties.
    
    Example:
        ```
        export VEZA_URL=<Veza URL>
        export VEZA_API_KEY=<Veza API key>
        ./idp-importer-csv.py --provider MyIdpProvider --datasource MyDatasource  ./my-users.csv
    
        ```
    
    Copyright 2022 Veza Technologies Inc.
    
    Use of this source code is governed by the MIT
    license that can be found in the LICENSE file or at
    https://opensource.org/licenses/MIT.
    
    """
    
    from oaaclient.client import OAAClient, OAAClientError
    from oaaclient.templates import CustomIdPProvider
    import click
    import csv
    import logging
    import os
    import sys
    
    
    logging.basicConfig(format='%(asctime)s %(levelname)s: %(message)s', level=logging.INFO)
    log = logging.getLogger()
    
    
    def load_users(idp: CustomIdPProvider, source: str) -> None:
        """Populate the idp with user from the source csv file"""
    
        log.info(f"Loading users from {source}")
        with open(source) as f:
            for r in csv.DictReader(f):
                # get the identity, name, full_name and email
                try:
                    identity = r["identity"]
                    name = r["name"]
                    full_name = r["full_name"]
                    email = r["email"]
                except KeyError as e:
                    log.error(f"Incorrect CSV column headers, missing column {e}")
                    sys.exit(1)
    
                # create a new IDP user
                new_user = idp.add_user(name=name, full_name=full_name, email=email, identity=identity)
    
                # set the user to active and guest or not, look for strings like true/false or yes/no
                if r.get("active"):
                    active_string = r["active"].lower()
                    if active_string in ["true", "yes"]:
                        new_user.is_active = True
                    elif active_string in ["false", "no"]:
                        new_user.is_active = False
    
                if r.get("is_guest"):
                    guest_string = r["is_guest"].lower()
                    if guest_string in ["true", "yes"]:
                        new_user.is_guest = True
                    elif guest_string in ["false", "no"]:
                        new_user.is_guest = False
    
                # if the manager id column is filled in, set the new users manager
                if r.get("manager_id"):
                    new_user.manager_id = r.get("manager_id")
    
        return
    
    @click.command()
    @click.option("--provider", required=True)
    @click.option("--datasource", required=True)
    @click.option("--save-json", is_flag=True)
    @click.argument("file", required=True)
    def main(provider, datasource, save_json, file):
    
        # load the Veza URL and API key from the environment
        veza_url = os.getenv("VEZA_URL")
        veza_api_key = os.getenv("VEZA_API_KEY")
    
        if not (veza_url or veza_api_key):
            log.error("Must set VEZA_URL and VEZA_API_KEY")
            sys.exit(1)
    
        try:
            log.info("Testing Veza credentials")
            veza_con = OAAClient(url=veza_url, api_key=veza_api_key)
        except OAAClientError as e:
            log.error("Unable to connect to Veza API")
            log.error(e)
            sys.exit(1)
    
        # create a new provider if the provider doesn't already exist
        if not veza_con.get_provider(provider):
            log.info(f"Creating new provider {provider}")
            veza_con.create_provider(provider, "identity_provider")
    
        # Configure the Custom IdP
        idp = CustomIdPProvider("Custom IdP", idp_type="custom_idp", domain="example.com", description=None)
    
        # load the user from
        load_users(idp, file)
    
        try:
            # push the IdP to Veza, log and errors or warnings
            log.info("Sending to Veza")
            response = veza_con.push_application(provider, datasource, idp, save_json=save_json)
            if response.get("warnings", None):
                log.warning("Push succeeded with warnings")
                for w in response['warnings']:
                    log.warning(w)
            log.info("Success")
        except OAAClientError as e:
            log.error(f"Error during push {e.message} {e.status_code}")
            if e.details:
                log.error(e.details)
            sys.exit(1)
    
        return
    
    if __name__ == "__main__":
        main()
    
    #!env python3
    """
    Copyright 2022 Veza Technologies Inc.
    
    Use of this source code is governed by the MIT
    license that can be found in the LICENSE file or at
    https://opensource.org/licenses/MIT.
    
    Example of using the `CustomApplication` class to model a typical application where users and groups are assigned
    permissions to the application or resources.
    
    If you want to run the code you will need to export environment variables for the Veza URL, user and API keys.
    
    ```
    export OAA_TOKEN="xxxxxxx"
    export VEZA_URL="https://myveza.vezacloud.com"
    ./sample-app.py
    ```
    
    """
    
    from oaaclient.client import OAAClient, OAAClientError
    from oaaclient.templates import CustomApplication, OAAPermission
    import os
    import sys
    
    
    def main():
    
        # OAA requires an API token, which you can generate from your Veza user profile
        # Export the API token, and Veza URL as environment variables
        # Making them available to your connector in this way keeps credentials out of the source code
        veza_api_key = os.getenv('VEZA_API_KEY')
        veza_url = os.getenv('VEZA_URL')
        if None in (veza_url, veza_api_key):
            print("Unable to local all environment variables")
            sys.exit(1)
    
        # Instantiates a client connection. The client will confirm the credentials and Veza URL are valid
        # Checking this early helps prevents connection failures in the final stage
        veza_con = OAAClient(url=veza_url, api_key=veza_api_key)
    
        # Create an instance of the OAA CustomApplication class, modeling the application name and type
        # `name` will be displayed in the Veza UI
        # `application_type` should be a short key reflecting the source application authorization is being modeled for
        # You can use the same type for multiple applications
        custom_app = CustomApplication(name="Sample App", application_type="sample")
    
        # In the OAA payload, each permission native to the custom app is mapped to the Veza effective permission (data/nondata C/R/U/D).
        # Permissions must be defined before they can be referenced, as they are discovered or ahead of time.
        # For each custom application permission, bind them to the Veza permissions using the `OAAPermission` enum:
        custom_app.add_custom_permission("admin", [OAAPermission.DataRead, OAAPermission.DataWrite])
        custom_app.add_custom_permission("operator", [OAAPermission.DataRead])
    
        # Create resources and sub-resource to model the entities in the application
        # To Veza, an application can be a single entity or can contain resources and sub-resources
        # Utilizing resources enables tracking of authorizations to specific components of the system being modeled
        # Setting a `resource_type` can help group entities of the same type for reporting/queries
        entity1 = custom_app.add_resource(name="Entity1", resource_type="thing", 
        entity2 = custom_app.add_resource(name="Entity2", resource_type="thing", 
        other = custom_app.add_resource(name="Other", resource_type="other", 
    
        # Sub-resources can be added to any resource (including other sub-resources)
        child1 = entity1.add_sub_resource(name="Child 1", resource_type="child", 
        child1.add_sub_resource(name="Grandchild 1", resource_type="grandchild", description=
    
        # Any users and groups local to the application can be defined.
        # IdP users can be mapped directly without defining them in the OAA application (see below)
        custom_app.add_local_user("bob")
        # A local user can be associated with an IdP user by adding an identity to the user:
        custom_app.local_users["bob"].add_identity("bob@example.com")
        # Identities, groups and roles can be assigned to local users at creation or after (groups and roles must exist):
        jane = custom_app.add_local_user("jane", identities="jane@example.com")
    
        # when adding a user the new user is returned and can updated if needed, there are multiple built in properties that can be set for a user
        jane.is_active = False
        jane.created_at = "2022-01-26T20:48:12.460Z"
    
        # Define a local group and add a user to it
        custom_app.add_local_group("admins")
        custom_app.local_users["jane"].add_group("admins")
    
        # adding local users and groups requires that the name not already exist
        if "yan" not in custom_app.local_users:
            custom_app.add_local_user("yan")
    
        # For each Identity (user, group, IdP) assign permissions to the application or resource.
        # The identities (users, groups) permissions and resources must already be defined
    
        # To add a permission directly to the application use `apply_to_application=True`
        custom_app.local_users["bob"].add_permission(permission="operator", apply_to_application=True
        custom_app.local_groups["admins"].add_permission(permission="admin",  apply_to_application=True
    
        # You can describe specific permissions to individual resources or sub-resources:
        custom_app.local_users["yan"].add_permission(permission="operator", resources=[
    
        # Authorization can also be created directly for an IdP identity
        custom_app.add_idp_identity("user_identity@example.com")
        # resources can also be referenced by name from the application model
        custom_app.idp_identities["user_identity@example.com"].add_permission(permission="admin", resources=[
    
        # Once all authorizations have been mapped, the final step is to publish the app to Veza
        # Connect to the API to Push to Veza, define the provider and create if necessary:
    
        provider_name = "Sample"
        provider = veza_con.get_provider(provider_name)
        if provider:
            print("-- Found existing provider")
        else:
            print(f"++ Creating Provider {provider_name}")
            provider = veza_con.create_provider(provider_name, "application")
        print(f"-- Provider: {provider['name']} ({provider['id'
    
        # Push the metadata payload:
    
        try:
            response = veza_con.push_application(provider_name,
                                                   data_source_name=f"{custom_app.name} ({custom_app.application_type})",
                                                   application_object=custom_app,
                                                   save_json=False
                                                   )
            if response.get("warnings", None):
                # Veza may return warnings on a successful uploads. These are informational warnings that did not stop the processing
                # of the OAA data but may be important. Specifically identities that cannot be resolved will be returned here.
                print("-- Push succeeded with warnings:")
                for e in response["warnings"]:
                    print(f"  - {e}")
        except OAAClientError as e:
            print(f"-- Error: {e.error}: {e.message} ({e.
            if hasattr(e, "details"):
                for d in e.details:
                    print(f"  -- {d}", file=sys.stderr)
        return
    
    
    if __name__ == '__main__':
        main()
    
    #!env python3
    """
    Copyright 2022 Veza Technologies Inc.
    
    Use of this source code is governed by the MIT
    license that can be found in the LICENSE file or at
    https://opensource.org/licenses/MIT.
    
    Example of using the `CustomIdPProvider` class to model an identity provider as a source of users.
    
    If you want to run the code you will need to export environment variables for the Veza URL, user and API keys.
    
    ```
    export VEZA_API_KEY="xxxxxxx"
    export VEZA_URL="https://myveza.vezacloud.com"
    ./sample-idp.py
    ```
    
    Since the example includes fake AWS ARNs that Veza will not have discovered the expected output will
    contain warning like "Cannot find IAM role by names ..."
    """
    
    from oaaclient.client import OAAClient, OAAClientError
    from oaaclient.templates import CustomIdPProvider, OAAPropertyType
    import os
    import sys
    
    
    def main():
    
        # OAA requires a Veza API key, which you can generate from Administration > API Keys
        # Export the API key, and Veza URL as environment variables
        # Making them available to your connector in this way keeps credentials out of the source code
        veza_api_key = os.getenv("VEZA_API_KEY")
        veza_url = os.getenv("VEZA_URL")
        if not veza_api_key or not veza_url:
            print("Unable to load VEZA_API_KEY and VEZA_URL from OS")
            sys.exit(1)
    
        # Instantiates a client connection. The client will confirm the credentials and Veza URL are valid
        # Checking this early helps prevents connection failures in the final stage
        veza_con = OAAClient(url=veza_url, api_key=veza_api_key)
    
        # create a CustomIdPProvider to represent your IdP. This can be named generically or specific to the environment if you have
        # multiple namespaces to model. idp_type will typically be the technology/vendor for the provider.
        idp = CustomIdPProvider("My IdP", domain="example.com", idp_type="
    
        # add users to the idp, properties for users can be set during creation or updated after
        idp.add_user("mrichardson", full_name="Michelle Richardson", email="mrichardson@example.com
    
        evargas_user = idp.add_user("evargas")
        evargas_user.full_name = "Elizabeth Vargas"
        evargas_user.email = "evargas@example.com"
    
        # users and groups can have optional identity property. The identity serves as the unique reference identifier across
        # Veza. If omitted CustomIdPProvider will automatically populate the identity with the name
        idp.add_user("willis", email="willis@example.com", identity="cwilliams
    
        # OAA can support custom properties for users to track additional metadata unique to the environment
        # to use custom properties the property must first be defined and given a type, then can be set for the individual entity
        idp.property_definitions.define_user_property("region", OAAPropertyType.STRING)
        idp.property_definitions.define_user_property("is_contractor", OAAPropertyType.BOOLEAN)
    
        idp.users['willis'].set_property("region", "NorthAmerica")
        idp.users['willis'].set_property("is_contractor", True)
    
        # Create Groups
        idp.add_group("developers")
        idp.add_group("sec-ops")
        idp.add_group("everyone", full_name="All Company Employees")
    
        # users can be added to groups using the add_group function, users can be added to multiple groups in a single call
        for username in idp.users:
            idp.users[username].add_groups(["everyone"])
    
        evargas_user.add_groups(["developers", "sec-ops"])
        idp.users["mrichardson"].add_groups(["developers"])
    
        # Veza CustomIdP supports tracking the AWS Roles a user can assume. For users who can assume roles Veza can calculate
        # their effective permissions to AWS resources based on the role(s)
        # roles are added by ARN
        idp.users["mrichardson"].add_assumed_role_arns(["arn:aws:iam::123456789012:role/role001", "arn:aws:iam::123456789012:role/role002"])
    
        # After adding users and groups, the IdP information is pushed to Veza using the OAA API
        provider_name = "Sample-IdP"
        provider = veza_con.get_provider(provider_name)
        if provider:
            print("-- Found existing provider")
        else:
            print(f"++ Creating Provider {provider_name}")
            provider = veza_con.create_provider(provider_name, "identity_provider")
        print(f"-- Provider: {provider['name']} ({provider['id'
    
        # Push the metadata payload:
        try:
            response = veza_con.push_application(provider_name,
                                                   data_source_name=f"{idp.name} ({idp.idp_type})",
                                                   application_object=idp,
                                                   save_json=True
                                                   )
            if response.get("warnings", None):
                # Veza may return warnings on a successful uploads. These are informational warnings that did not stop the processing
                # of the OAA data but may be important, for example: AWS role ARNs assigned to users that Veza has not discovered
                print("-- Push succeeded with warnings:")
                for e in response["warnings"]:
                    print(f"  - {e}")
        except OAAClientError as e:
            print(f"-- Error: {e.error}: {e.message} ({e.
            if hasattr(e, "details"):
                for d in e.details:
                    print(f"  -- {d}", file=sys.stderr)
    
    
    if __name__ == '__main__':
        main()
    

    OAA Python SDK

    Building blocks for your custom OAA integration

    oaaclient can be downloaded from , or installed with pip3 install oaaclient.

    The oaaclient package provides data models, methods and a command-line interface for using the Open Authorization API. You can use it to populate OAA templates including Application, IdP, HRIS, Host, Principal, Secret Store, and Entity Enrichment, pushing OAA data to Veza and even as a general Veza API client.

    The oaaclient SDK includes the following components:

    • oaaclient.client: Veza API communication (data provider management, payload push, etc.). Requires an API key for authentication.

    • oaaclient.templates: Classes for modeling and generating an OAA payload.

    • oaaclient.utils: Additional utility functions (icon encoding, etc.).

    For example usage, please see and the directory.

    Sample Workflow

    Create the Veza API connection and a new custom application:

    Once the CustomApplication class is instantiated, you can use the public methods to populate the new app with local users, groups, resources, and permissions metadata:

    Once all identities, permissions and resources are added to the CustomApplication object, the client connection handles the final push to Veza:

    See the directory for complete examples.

    The OAAClient class handles API connections to Veza. If there are errors connecting or the API returns errors OAAClient will raise an OAAClientError exception. If the payload doesn't conform to the template requirements the OAAClientError.details will contain a list of any issues encountered.

    Since any given source application or service will have different methods for retrieving entities, authorization, and other required metadata, each OAA connector will be slightly different. You should consult the API documentation for your application when considering how you will source the information, and refer to existing Veza-supported OAA connectors for real-world examples.

    Connector source code and oaaclient are thoroughly annotated, for reference when building your own integrations.

    For additional information about developing a custom OAA integration, please see section of the User Guide.

    description
    =
    "
    Some entity in the application
    "
    )
    description
    =
    "
    Another entity in the application
    "
    )
    description
    =
    "
    Something totally different
    "
    )
    description
    =
    "
    My information about resource
    "
    )
    "
    My information about resource
    "
    )
    )
    )
    entity1
    ,
    child1
    ])
    custom_app
    .
    resources
    [
    '
    Entity1
    '
    ]])
    ]
    }
    )"
    )
    status_code
    }
    )"
    ,
    file
    =
    sys
    .
    stderr
    )
    custom_idp
    "
    )
    "
    )
    "
    )
    ]
    }
    )"
    )
    status_code
    }
    )"
    ,
    file
    =
    sys
    .
    stderr
    )

    Handling Errors

    Additional documentation

    modules
    samples
    GitHub quickstarts
    modules
    Open Authorization API
    GitHub
    from oaaclient.client import OAAClient
    from oaaclient.templates import CustomApplication, OAAPermission
    
    # creates a connection class to communicate with Veza
    veza_con = OAAClient(url=veza_url, token=veza_api_key)
    
    # creates a new Custom Application model
    custom_app = CustomApplication(name="Sample App", application_type="sample")
    # define a permission
    custom_app.add_custom_permission("owner", [OAAPermission.DataRead, OAAPermission.DataWrite])
    # create a local user
    jsmith = custom_app.add_local_user(unique_id="jsmith", name="Jane Smith", identities=["jane@example.com"])
    # create a resource
    resource1 = custom_app.add_resource(name="Resource 1", resource_type="Thing")
    # assign a user to a resource
    jsmith.add_permission(permission="owner", resources=[resource1])
    veza_con.push_application(provider, data_source_name, application_object=custom_app)
        try:
            response = veza_con.push_application(provider_name=provider_name,
                                                 data_source_name=data_source_name,
                                                 application_object=custom_app,
                                                )
            if response.get("warnings"):
                print("Push succeeded with warnings:")
                for w in response["warnings"]:
                    print(w)
        except OAAClientError as e:
            print(f"Error: {e.error}: {e.message} ({e.status_code})", file=sys.stderr)
            if hasattr(e, "details"):
                for d in e.details:
                    print(d, file=sys.stderr)

    Custom Principal

    Template for modeling a lightweight identity source with users, groups, and tenants

    Use this template to model a source of identities (users, groups, and tenants) using the Open Authorization API. Principals represent identity sources that connect to other OAA template types on the same provider, enabling Veza to map users and groups to the applications and resources they access.

    The Custom Principal template differs from the Custom Identity Provider in scope: a Principal is a lightweight identity source meant to feed users and groups into Custom Application or other templates on the same provider. Custom IdP models a full identity provider with domains and federated identity features.

    The template has three primary entities:

    • Tenant - the top-level container for the principal instance. Each submission has exactly one tenant.

    • Users - the individual identities in the principal system. Users can belong to groups and have custom properties like is_active, email, and timestamps.

    • Groups - collections of users. Groups support hierarchical nesting through parent group references.

    A can define additional properties for tenants, users, and groups.

    To use the principal template, set custom_templates to a list that includes principal when creating the provider. Because a principal is almost always used alongside an application, include both templates:

    Then create a data source for the principal on that provider, specifying the principal template:

    Veza's Atlassian Cloud connector uses the Custom Principal template to model the organization-level identity directory in Atlassian Cloud. The principal feeds users and groups into the Jira Cloud and Confluence Cloud application connectors on the same provider, linking identities to the resources they access.

    This approach separates identity management (who exists, what products they can access) from application-level authorization (what permissions they have in Jira projects or Confluence spaces). The principal captures the organization directory, while separate Custom Application submissions model Jira and Confluence.

    Key patterns from this integration:

    • user_type distinguishes managed users (in the organization's domain) from external collaborators, enabling access reviews to flag external access.

    • product_access as a STRING_LIST tracks which Atlassian products each user can access (Jira, Confluence, Bitbucket), providing visibility into license usage.

    • access_billable flags whether the user counts toward the organization's Atlassian license seat count.

    Field
    Type
    Description

    Each principal submission contains exactly one tenant, representing the top-level container for the identity source.

    Field
    Type
    Description

    Users represent individual identities in the principal system. Each user can be linked to external identities and assigned to groups.

    Field
    Type
    Description

    Groups represent collections of users. Groups can have external identities and support hierarchical nesting through parent group references.

    Field
    Type
    Description

    Custom properties allow you to attach additional metadata to principal entities. Define properties in the custom_property_definition object, then set values on individual entities.

    Scope
    Description

    Property values must match their declared type. Supported types are described in .

    After the initial metadata push (which must contain the full payload), you can modify, add, or remove the tenant, users, and groups without resubmitting other entities. An is enabled by setting "incremental_change": true in the push payload, and specifying the update operation for each entity to change.

    To create the OAA provider and push data:

    1. Create the provider with both the principal and application template types:

    2. Create a data source on the provider, specifying the principal template:

    3. Push the payload to the data source:

      The push endpoint requires the payload as a JSON-encoded string in the json_data

    Updates follow the same push workflow. Veza processes the full payload and updates the Authorization Graph accordingly.

  • Groups map to product access rather than organizational structure — groups like jira-software-users and confluence-users reflect Atlassian's product-based access model.

  • The principal connects to application templates on the same provider. Users and groups defined here appear as identities in Jira Cloud and Confluence Cloud Custom Application submissions, linking organization membership to application-level permissions.

  • object

    The object for this principal

    users

    array

    Array of objects

    groups

    array

    Array of objects

    incremental_change

    boolean

    When true, enables (optional)

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    validated against the custom_property_definition

    operation

    enum

    For , the operation to apply (optional)

    user_unique_id

    string

    Optional unique identifier. Defaults to email if set, otherwise id

    display_name

    string

    Display name shown in Veza (optional)

    is_active

    boolean

    Whether the user account is active

    created_date

    string

    Date the user was created, in RFC 3339 format (e.g., 2024-01-15T09:00:00.000Z)

    deactivated_date

    string

    Date the user was deactivated, in RFC 3339 format (optional)

    last_login

    string

    Date of the user's last login, in RFC 3339 format (optional)

    identities

    array

    List of identity strings (e.g., email addresses) used for linking to external identity providers

    groups

    array

    List of group references as {"id": "group_id"} objects

    tags

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    validated against the custom_property_definition

    operation

    enum

    For , the operation to apply (optional)

    string

    Type descriptor for the group (e.g., Security, Department, Team)

    parent_group

    object

    Reference to a parent group as {"id": "parent_group_id"} for hierarchical nesting (optional)

    identities

    array

    List of identity strings for linking to external identity providers

    tags

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    validated against the custom_property_definition

    operation

    enum

    For , the operation to apply (optional)

    field.
    jq -Rs .
    reads
    payload.json
    and escapes it as a JSON string.
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"Principal Data Source","custom_template":"principal"}'

    name

    string

    Name of the principal provider instance

    principal_type

    string

    Type descriptor for the principal provider (e.g., corporate_directory). Applied as a searchable property

    custom_property_definition

    object

    Defines custom properties for tenants, users, and groups. See Custom Properties

    "tenant": {
      "name": "Example Corp",
      "id": "tenant-001",
      "tenant_unique_id": "tenant-001",
      "tags": [],
      "custom_properties": {}
    }

    name

    string

    Display name for the tenant

    id

    string

    Unique identifier for the tenant

    tenant_unique_id

    string

    Optional unique identifier, typically a URL or external ID. Defaults to id if not provided

    "users": [
      {
        "name": "Alice Johnson",
        "id": "alice01",
        "email": "alice@example.com",
        "user_unique_id": "alice01",
        "display_name": "Alice Johnson",
        "is_active": true,
        "created_date": "2024-01-15T09:00:00.000Z",
        "last_login": "2025-02-20T14:30:00.000Z",
        "identities": ["alice@example.com"],
        "groups": [{"id": "grp-engineering"}],
        "tags": [],
        "custom_properties": {}
      }
    ]

    name

    string

    Display name for the user

    id

    string

    Unique identifier for the user. Defaults to name if not provided

    email

    string

    Email address for the user (optional)

    "groups": [
      {
        "name": "Engineering",
        "id": "grp-engineering",
        "group_unique_id": "grp-engineering",
        "group_type": "Department",
        "identities": ["engineering@example.com"],
        "tags": [],
        "custom_properties": {}
      },
      {
        "name": "Platform Team",
        "id": "grp-platform",
        "group_type": "Team",
        "parent_group": {
          "id": "grp-engineering"
        }
      }
    ]

    name

    string

    Display name for the group

    id

    string

    Unique identifier for the group. Defaults to name if not provided

    group_unique_id

    string

    Optional unique identifier for the group. Defaults to id if not provided

    "custom_property_definition": {
      "tenant_properties": {
        "region": "STRING"
      },
      "user_properties": {
        "department": "STRING",
        "mfa_enabled": "BOOLEAN"
      },
      "group_properties": {
        "is_security_group": "BOOLEAN"
      }
    }

    tenant_properties

    Custom properties for the tenant entity

    user_properties

    Custom properties for user entities

    group_properties

    Custom properties for group entities

    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"ExampleCorp","custom_templates":["principal","application"]}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"Principal Data Source","custom_template":"principal"}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data "{\"json_data\": $(jq -Rs . payload.json)}"

    Sample Payloads

    Custom Principal with Users and Groups

    This example demonstrates a corporate directory with users assigned to groups, custom properties, and hierarchical group nesting.

    {
      "custom_property_definition": {
        "tenant_properties": {
          "region": "STRING"
        },
        "user_properties": {
          "department": "STRING",
          "mfa_enabled": "BOOLEAN"
        },
        "group_properties": {
          "is_security_group": "BOOLEAN"
        }
      },
      "name": "Example Corp",
      "principal_type": "corporate_directory",
      "tenant": {
        "name": "Example Corp",
        "id": "tenant-001",
        "tenant_unique_id": "tenant-001",
        "tags": [
          {
            "key": "environment",
            "value": "production"
          }
        ],
        "custom_properties": {
          "region": "us-west-2"
        }
      },
      "users": [
        {
          "name": "Alice Johnson",
          "id": "alice01",
          "email": "alice@example.com",
          "user_unique_id": "alice01",
          "display_name": "Alice Johnson",
          "is_active": true,
          "created_date": "2024-01-15T09:00:00.000Z",
          "last_login": "2025-02-20T14:30:00.000Z",
          "identities": [
            "alice@example.com"
          ],
          "groups": [
            {
              "id": "grp-engineering"
            }
          ],
          "custom_properties": {
            "department": "Engineering",
            "mfa_enabled": true
          }
        },
        {
          "name": "Bob Smith",
          "id": "bob02",
          "email": "bob@example.com",
          "user_unique_id": "bob02",
          "is_active": true,
          "identities": [
            "bob@example.com"
          ],
          "groups": [
            {
              "id": "grp-engineering"
            },
            {
              "id": "grp-admins"
            }
          ],
          "custom_properties": {
            "department": "Engineering"
          }
        }
      ],
      "groups": [
        {
          "name": "Engineering",
          "id": "grp-engineering",
          "group_unique_id": "grp-engineering",
          "group_type": "Department",
          "identities": [
            "engineering@example.com"
          ],
          "custom_properties": {
            "is_security_group": false
          }
        },
        {
          "name": "Admins",
          "id": "grp-admins",
          "group_unique_id": "grp-admins",
          "group_type": "Security",
          "custom_properties": {
            "is_security_group": true
          }
        },
        {
          "name": "Platform Team",
          "id": "grp-platform",
          "group_unique_id": "grp-platform",
          "group_type": "Team",
          "parent_group": {
            "id": "grp-engineering"
          }
        }
      ]
    }

    Real-World Example: Atlassian Cloud Admin

    Atlassian Cloud Admin Payload

    This payload models an Atlassian Cloud organization with managed and external users, product-access groups, and custom properties tracking account metadata.

    {
      "custom_property_definition": {
        "user_properties": {
          "account_type": "STRING",
          "account_status": "STRING",
          "access_billable": "BOOLEAN",
          "product_access": "STRING_LIST",
          "user_type": "STRING"
        },
        "group_properties": {
          "description": "STRING"
        }
      },
      "name": "Atlassian Cloud Admin",
      "principal_type": "Atlassian Cloud Admin",
      "tenant": {
        "name": "acme-corp",
        "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
        "tenant_unique_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
      },
      "users": [
        {
          "name": "Jane Doe",
          "id": "5b10ac8d82e05b22cc7d4ef5",
          "email": "jane.doe@acme-corp.com",
          "user_unique_id": "5b10ac8d82e05b22cc7d4ef5",
          "is_active": true,
          "identities": [
            "jane.doe@acme-corp.com"
          ],
          "groups": [
            {
              "id": "jira-software-users"
            },
            {
              "id": "confluence-users"
            }
          ],
          "custom_properties": {
            "account_type": "atlassian",
            "account_status": "active",
            "access_billable": true,
            "product_access": ["jira-software", "confluence"],
            "user_type": "managed"
          }
        },
        {
          "name": "ext-contractor@partner.com",
          "id": "7c20bd9e93f16c33dd8e5fg6",
          "email": "ext-contractor@partner.com",
          "user_unique_id": "7c20bd9e93f16c33dd8e5fg6",
          "is_active": true,
          "identities": [
            "ext-contractor@partner.com"
          ],
          "groups": [
            {
              "id": "jira-software-users"
            }
          ],
          "custom_properties": {
            "account_type": "atlassian",
            "account_status": "active",
            "access_billable": true,
            "product_access": ["jira-software"],
            "user_type": "external"
          }
        }
      ],
      "groups": [
        {
          "name": "jira-software-users",
          "id": "jira-software-users",
          "group_unique_id": "jira-software-users",
          "group_type": "product-access",
          "custom_properties": {
            "description": "Users with access to Jira Software"
          }
        },
        {
          "name": "confluence-users",
          "id": "confluence-users",
          "group_unique_id": "confluence-users",
          "group_type": "product-access",
          "custom_properties": {
            "description": "Users with access to Confluence"
          }
        },
        {
          "name": "org-admins",
          "id": "org-admins",
          "group_unique_id": "org-admins",
          "group_type": "admin",
          "custom_properties": {
            "description": "Organization administrators"
          }
        }
      ]
    }

    Top-Level Payload

    Tenant

    Tenant Properties

    Users

    User Properties

    Groups

    Group Properties

    Custom Property Definitions

    Incremental Updates

    Creating and Updating a Custom Principal

    custom property definition
    Custom Properties
    incremental update

    tenant

    tags

    group_type

    Client

    Classes for calling Veza APIs and managing OAA providers and data sources.

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • OAACLIENT_VERSION

    • PROVIDER_ICON_MAX_SIZE


    function report_builder_entrypoint

    report_builder_entrypoint() → None

    Entry point for oaaclient-report-builder command

    Reads a JSON file and passes it to the oaaclient.utils.build_report method



    Error raised by OAAClient.

    Raised for issues connecting to the OAA API and when the API returns an error.

    Args:

    • error (str): short string for error message

    • message (str): detailed error message

    • status_code (int, optional): status code for HTTP related errors. Defaults to None.


    Error returned from API Call


    Error with API Connection


    Class for OAA API Connection and Management.

    Utilities for OAA-related operations with Veza API calls. Manages custom providers and data sources, and can push OAA payloads from JSON or template objects.

    Connection url and API key can be automatically loaded from OS environment values if set. To utilize environment variables initialize OAAClient without providing a URL or API key value and set the VEZA_URL and VEZA_API_KEY OS environment variables.

    Args:

    • url (str, optional): URL for Veza instance.

    • api_key (str, optional): Veza API key.

    • username (str, optional): Not used (legacy). Defaults to None.

    Attributes:

    • url (str): URL of the Veza instance to connect to

    • api_key (str): Veza API key

    • enable_compression (bool): Enable or disable compression of the OAA payload during push, defaults to enabled (True)

    Raises:

    • OAAClientError: For errors connecting to API and if API returns errors


    Add a Query to a Report

    Adds a Query to an existing Report by ID

    Args:

    • report_id (str): Report UUID to add Query to

    • query_id (str): Query UUID to add

    Returns:

    • dict: API Response


    Perform REST API DELETE operation.

    Args:

    • api_path (str): API Path API path relative to Veza URL

    Raises:

    • OAAResponseError: API returned an error

    • OAAConnectionError: Connection error during HTTP operation

    Returns:

    • dict: API response from call


    Perform a Veza API GET operation.

    Makes the GET API call to the given path and processes the API response. Returns the value or values result returned from the API.

    • For API endpoints that return a list like /api/v1/providers/custom function will return a list of entities or an empty list if the API returns no results.

    • For API endpoints that are a specific ID such as /api/v1/providers/custom/<uuid> function will return the dictionary result of the JSON returned by the API.

    Args:

    • api_path (str): API path relative to Veza URL (example /api/v1/providers).

    Raises:

    • OAAResponseError: API returned an error

    • OAAConnectionError: Connection error during HTTP operation

    Returns:

    • list|dict: Returns list or dict based on API destination


    Perform REST API PATCH operation.

    Args:

    • api_path (str): API Path API path relative to Veza URL

    Raises:

    • OAAResponseError: API returned an error

    • OAAConnectionError: Connection error during HTTP operation

    Returns:

    • dict: API response from call


    Perform a Veza API POST operation.

    Call POST on the supplied Veza instance API path, submitting a data payload.

    Returns value or values response from API result. Paginated responses are automatically processed to collect all responses a single list.

    Args:

    • api_path (str): API path relative to Veza URL example /api/v1/providers

    • data (dict): dictionary object included as JSON in body of POST operation

    • params (dict, optional): Optional HTTP query parameters. Defaults to empty dictionary.

    Raises:

    • OAAResponseError: API returned an error

    • OAAConnectionError: Connection error during HTTP operation

    Returns:

    • dict: API response as dictionary


    Perform Veza API PUT operation.

    Call PUT on the supplied Veza instance API path, including the data payload.

    Returns value or values response from API result. Paginated responses are automatically processed to collect all responses a single list.

    Args:

    • api_path (str): API path relative to Veza URL example /api/v1/providers

    • data (dict): dictionary object included as JSON in body of PUT operation

    • params (dict, optional): Optional HTTP query parameters. Defaults to empty dictionary.

    Raises:

    • OAAResponseError: API returned an error

    • OAAConnectionError: Connection error during HTTP operation

    Returns:

    • dict: API response as dictionary


    Create a new Data Source for the given Provider ID.

    Args:

    • name (str): Name for new Data Source

    • provider_id (str): Unique identifier for the Provider

    • options: (dict, optional): Additional arguments to be included with data source create call to Veza. Defaults to None.

    Raises:

    • ValueError: Data source name contains invalid characters

    Returns:

    • dict: dictionary of new Data Source


    Deprecated Legacy function for backward-compatibility.


    Create a new Provider.

    Creates a new Provider with the given name. An error will be raised for naming conflicts.

    Args:

    • name (str): new Provider name

    • custom_template (str): the OAA template to use for the Provider ("application" or "identity_provider")

    • base64_icon (str, optional): Base64 encoded string of icon to set for Provider. Defaults to "".

    Raises:

    • ValueError: Provider name contains invalid characters

    Returns:

    • dict: dictionary representing the created Provider


    Create a new Assessment Query

    For details on how to define an Assessment Query see the Veza docs.

    Args:

    • query (dict): Query definition

    Returns:

    • dict: API response including ID of created Query


    Create a new Report

    For details on how to define a new Report see the Veza docs.

    Args:

    • report (dict): Report definition

    Returns:

    • dict: API response including ID of created Report


    Push OAA Payload

    Uploads the OAA payload to the datasource :push operation

    Args:

    • provider_id (str): Provider ID

    • datasource_id (str): Datasource ID

    • payload (str): OAA payload as string

    • options

    Raises:

    • ValueError: Invalid optionas format

    • OAAClientError: Errors returned by Veza API

    Returns:

    • dict: API response


    Push OAA Payload in parts

    Push the data source payload in parts using the :push-parts operation. Necessary for large payloads.

    Function will automatically start a multipart upload, split the payload into parts to upload and return the output from the complete upload operation which is the same output as from a normal OAA data source :push operation. Returned result will include any OAA validation warnings or errors.

    Args:

    • provider_id (str): Provider ID

    • datasource_id (str): Data source ID

    • json_data (str): OAA Payload JSON as string

    Raises:

    • ValueError: Input errors

    • OAAClientError: Errors returned by the Veza API

    Returns:

    • dict: API response of upload complete operation


    Delete an existing Data Source by ID.

    Removes a Data Source and all entity data.

    Args:

    • data_source_id (str): ID of Data Source to delete

    • provider_id (str): ID of Data Source Provider

    Returns:

    • dict: API response


    Delete an existing provider by ID.

    Deleting a provider removes all datasources and historical data. Fully deleting the provider is a background operation that will complete after API response is returned.

    Args:

    • provider_id (str): ID of provider to delete

    Returns:

    • dict: API response


    Delete an Assessment Query by ID

    Args:

    • id (str): UUID of Query to delete

    • force (bool): Force deletion of query that may be part of a report. Defaults to False

    Returns:

    • dict: API response from delete


    Delete Report by ID

    Args:

    • id (str): UUID of Report to delete

    Returns:

    • dict: API response


    Get Provider's Data Source by name.

    Find a Data Source from a specific provider based on the name of the Data Source

    Args:

    • name (str): Data Source name

    • provider_id (str): Provider unique ID

    Returns:

    • dict: Data Source as dict or None


    Get Data Sources for Provider by ID.

    Get the list of existing Data Sources, filtered by Provider UUID.

    Args:

    • provider_id (str): ID of Provider

    Returns:

    • list[dict]: List of Data Sources as dictionaries


    Get Provider by name.

    Args:

    • name (str): name of Provider

    Returns:

    • dict: dictionary representing Provider or None


    Get Provider by UUID identifier.

    Args:

    • provider_id (str): Unique global identifier for provider

    Returns:

    • dict: dictionary representation of Provider or None


    Return list of Providers.

    Returns:

    • list[dict]: Returns a list of existing Providers as dictionaries


    Get all saved Assessment Queries

    Veza can filter out queries that include inactive entity types (e.g. Okta Users on a system without Okta configured). To only retrieve queries that include active entity types set include_inactive_queries to False.

    Args:

    • include_inactive_queries (bool): Set False to exclude inactive queries from result. Defaults to True.

    Returns:

    • list: List of assessment Queries as dictionaries


    Get Assessment Query by ID

    Args:

    • id (str): UUID identifier for Query

    Returns:

    • dict: Query definition


    Get Report by ID

    Veza can filter out queries from reports that only contain entity types that are not configured (e.g. Okta Users on a system without Okta configured). To only return queries configured on the report that match entity types configured on the system set include_inactive_queries to False

    Args:

    • id (str): UUID of Report to get

    • include_inactive_queries (bool): Set True to include inactive queries. Default True.

    Returns:

    • dict: Report definition


    Get all Reports

    Gets Reports created on the system. To get all reports include_inactive_reports and include_inactive_queries must be set to True.

    Args:

    • include_inactive_reports (bool, Optional): Set to True to include reports that contain no active providers, defaults to True.

    • include_inactive_queries (bool, Optional): Set to True to include reports that contain only inactive queries, defaults to True.

    Returns:

    • list[dict]: List of Reports as dictionary objects


    Push an OAA Application Object (such as CustomApplication).

    Extracts the OAA JSON payload from the supplied OAA class (e.g. CustomApplication, CustomIdPProvider, EntityEnrichment etc) and push to the supplied Data Source.

    The Provider with provider_name must be a valid existing Provider or create_provider must be set to True. A new data source will be created automatically by default if it does not already exist.

    For logging, and debugging, the optional save_json flag writes the payload to a local file (before push). Output file name is formatted with a timestamp: {data source name}-{%Y%m%d-%H%M%S}.json

    Args:

    • provider_name (str): Name of an existing Provider.

    • data_source_name (str): Name for Data Source (will be created if it doesn't exist).

    • application_object (Class): OAA object to extract the payload from

    Raises:

    • OAAClientError: If any API call returns an error (including errors processing the OAA payload).

    Returns:

    • dict: API response from push, including any warnings that are returned.


    Push an OAA payload dictionary to Veza.

    Publishes the supplied metadata dictionary representing an OAA payload to the specified provider and data source. The function will create a new data source if it does not already exist, but requires the Provider be created ahead of time.

    Args:

    • provider_name (str): Name of existing Provider

    • data_source_name (str): Name for Data Source, will be created if doesn't exist.

    • metadata (dict): Dictionary of OAA payload to push.

    Raises:

    • OAAClientError: If any API call returns an error including errors processing the OAA payload.

    Returns:

    • dict: API response to the push request (including any warnings).


    Update an existing custom provider icon from base64 encoded string.

    To load an icon from file, use utils.encode_icon_file to get the base64 encoding of the file first

    Args:

    • provider_id (str): unique ID of existing provider

    • base64_icon (str): base64 encoded string of new icon

    Raises:

    • ValueError: If icon size exceeds maximum allowed size


    Update HRIS provider to be a system of record for Lifecycle Management (LCM).

    Args:

    • provider_id (str): unique ID of existing provider

    • provisioning (bool): set to True to enable LCM, False to disable


    Update an existing report

    Args:

    • report_id (str): UUID of Report to updated

    • report (dict): Updated Report definition

    Returns:

    • dict: API response


    Updates the User-Agent string passed with all API calls

    Generates a User-Agent with the oaaclient version, Python version and platform information.

    The optional extra string will be appended if provided.

    Args:

    • extra (str, optional): Additional information to append to User-Agent string. Defaults to "".


    Super class for urllib3.util.retry

    Super class to allow modifying the default max backoff time from 120 seconds to our own value

    Args:

    • Retry (type): description

    Host

    Classes for constructing an OAA JSON payload for the Host template

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • PROPERTY_NAME_REGEX


    class HostGranteeType

    Whether a HostGrant's principal is a user or a group.


    class HostIdentityType

    Whether a HostUser stands for a person or not.


    class HostProvider

    Class for modeling host machine authorization using the OAA Host template.

    A Host provider supports two collection models, distinguished by shape rather than a mode flag. A central collector with visibility of the whole fleet calls add_environment() once and add_host() for every host in the fleet. An agent running on one host has no view of the fleet, so it calls add_host(environment_id=...) for its own host alone and does not call add_environment().

    What distinguishes the two is where the environment comes from, not how many hosts are submitted. A submission that carries an environment of its own and also sets environment_id on a host, or that does neither, is rejected by the server as ambiguous.

    Args:

    • host_type (str): Type descriptor for the fleet, typically the platform or vendor name

    Attributes:

    • host_type (str): Type for the fleet

    • environment (HostEnvironment): The fleet's environment, set by add_environment(). None for a per-host agent submission.

    • hosts (dict[HostNode]): Dictionary of HostNode instances


    Add the fleet's environment.

    Only used by a central collector that has visibility of the whole fleet. A per-host agent submission names its environment with add_host(environment_id=...) instead and must not call this method.

    Args:

    • unique_id (str): Unique ID for the environment. Required.

    • name (str): Display name for the environment. Required.

    • description (str, optional): Description for the environment. Defaults to None.

    Raises:

    • OAATemplateException: If an environment has already been added to this submission.

    Returns: HostEnvironment


    Add a new Host.

    Hosts can be referenced after creation using the .hosts dictionary attribute, keyed case insensitively by unique_id.

    Args:

    • name (str): Display name for host. Required.

    • unique_id (str): Unique identifier for host for reference by ID. Required.

    • environment_id (str, optional): ID of the Environment this host belongs to. Required when this submission carries no environment of its own (a per-host agent submission); must be absent when add_environment() has been called on this provider. Defaults to None.

    Raises:

    • OAATemplateException: name or unique_id is empty, or host is already defined.

    Returns: HostNode


    Add a new privilege definition.

    Privileges are defined once on the fleet and referenced by name wherever they are granted via HostNode.add_grant().

    Args:

    • name (str): Name grants refer to

    • privilege_type (list[OAAPermission]): Canonical access types this privilege confers

    • description (str, optional): Description for privilege. Defaults to None.

    Raises:

    • OAATemplateException: name is empty, or privilege with name already exists.

    Returns: HostPrivilegeDefinition


    Get the OAA payload.

    Returns the complete OAA template payload for the host fleet as serializable dictionary

    Returns:

    • dict: OAA payload as dictionary


    Environment for a Host fleet.

    Represents the fleet-wide information for a Host submission. Created by HostProvider.add_environment().

    Args:

    • unique_id (str): Unique ID for the environment. Required.

    • name (str): Display name for the environment. Required.

    • description (str, optional): Description for the environment. Defaults to None.

    Raises:

    • ValueError: unique_id or name is empty.

    • OAATemplateException: An identity_provider_types value is not a known IdP kind.


    Output function for payload.


    A single host machine.

    Contains the host's own users, groups, credentials, resources and grants. Created by HostProvider.add_host().

    Args:

    • name (str): Display name for host. Required.

    • unique_id (str): Unique identifier for host. Required.

    • environment_id (str, optional): ID of the Environment this host belongs to. Required for a per-host agent submission, which carries no environment of its own; must be absent when the submission carries an environment. Defaults to None.

    Attributes:

    • platform (str): Host platform, e.g. "linux". None until set.

    • version (str): Host platform version, e.g. "Ubuntu 22.04.4 LTS". None until set.

    • ip_address (str): Host IP address. None until set.

    Raises:

    • ValueError: name or unique_id is empty.


    Add a new credential to this host.

    A credential is a way of authenticating as an account, such as an SSH key. It carries no privileges of its own; it identifies which account its holder becomes.

    Args:

    • name (str): Display name for credential. Required.

    • unique_id (str): Unique identifier for credential. Required.

    • credential_type (str, optional): Type for credential. Defaults to None.

    Raises:

    • OAATemplateException: name or unique_id is empty, or credential already defined.

    Returns: HostCredential


    Grant privileges to a principal on this host.

    Records which privileges a user or group holds, on the host itself, on resources inside it, or both.

    Calling this again for the same principal_id and grantee_type adds to the existing grant where the call applies to the same things, and creates a second grant where it does not. A principal holding sudo on one command and login on the host holds two differently scoped sets of privileges, and they stay apart; a second call naming the same command adds to the first. The same id used for both a user and a group grant likewise produces two separate grants.

    Args:

    • principal_id (str): ID of the user or group holding the privileges. Must be declared among this host's users or groups when is_local is True.

    • grantee_type (HostGranteeType): Whether principal_id names a user or a group.

    • is_local (bool, optional): Whether the principal is declared on this host. False for a directory-backed principal, whose identity provider's connector draws the edge from it. Defaults to True.

    Raises:

    • OAATemplateException: principal_id is empty, grantee_type is not a HostGranteeType, a privileges entry is not a name or an object carrying one, or a resources entry is empty or not the expected type.


    Add a new group to this host.

    Args:

    • name (str): Display name for group. Required.

    • unique_id (str): Unique identifier for group. Required.

    • group_type (str, optional): Type for group. Defaults to None.

    Raises:

    • OAATemplateException: name or unique_id is empty, or group already defined.

    Returns: HostGroup


    Add a new resource to this host.

    A resource is something inside the host that a privilege can apply to, such as a service or a command, rather than the host as a whole.

    A unique_id is unique within a resource_type rather than across the host, so a service and a container may both be called postgres.

    Args:

    • name (str): Display name for resource. Required.

    • unique_id (str): Unique identifier for resource within the resource_type. Required.

    • resource_type (str): The kind of thing this is, e.g. "service" or "command". Must not contain a "." or ":" character. Required.

    Raises:

    • OAATemplateException: name, unique_id or resource_type is empty, a resource of the same type and unique_id is already defined, or resource_type contains a "." or ":" character.

    Returns: HostResource


    Add a new user account to this host.

    A user belongs to exactly one host: root on two hosts is two accounts, each added separately.

    Args:

    • name (str): Display name for user. Required.

    • unique_id (str): Unique identifier for user. Required.

    • identities (list[str], optional): The identities in an identity provider this account belongs to. Required when is_local is False. Defaults to None.

    Raises:

    • OAATemplateException: name or unique_id is empty, user already defined, or identity_type is not a HostIdentityType.

    Returns: HostUser


    Set a custom property value for the host.

    Property name must be defined for the fleet before calling set_property. See HostPropertyDefinitions.define_host_property for more information.

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property name is not defined.


    Output function for payload.


    A user account on a Host.

    A user belongs to exactly one host: root on two hosts is two accounts, each with its own last_login_at and is_active. Created by HostNode.add_user().

    Args:

    • name (str): Display name for user. Required.

    • unique_id (str): Unique identifier for user. Required.

    • identities (list[str], optional): The identities in an identity provider this account belongs to. Defaults to None.

    Raises:

    • ValueError: name or unique_id is empty.

    • OAATemplateException: identity_type is not a HostIdentityType.


    Add this user to a group.

    Group must also be defined on the host with HostNode.add_group().

    Args:

    • group_id (str): ID of the group to add user to.

    Raises:

    • OAATemplateException: group_id is empty.


    Set a custom property value for the user.

    Property name must be defined for the fleet's users before calling set_property.

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property name is not defined.


    Output function for payload.


    A group on a Host.

    Created by HostNode.add_group().

    Args:

    • name (str): Display name for group. Required.

    • unique_id (str): Unique identifier for group. Required.

    • group_type (str, optional): Type for group. Defaults to None.

    Raises:

    • ValueError: name or unique_id is empty.


    Add a member group.

    A member may be another group on the same host, or a directory-backed group with no local definition.

    Args:

    • group_id (str): ID of the member group.

    • is_local (bool, optional): Whether the member group is declared on this host. Defaults to True.

    Raises:

    • OAATemplateException: group_id is empty.


    Set a custom property value for the group.

    Property name must be defined for the fleet's groups before calling set_property.

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property name is not defined.


    Output function for payload.


    A credential that authenticates as an account on a Host.

    A credential is a way of authenticating as an account, such as an SSH key. It carries no privileges of its own; it identifies which account its holder becomes. Created by HostNode.add_credential().

    Credentials have no custom properties.

    Args:

    • name (str): Display name for credential. Required.

    • unique_id (str): Unique identifier for credential. Required.

    • credential_type (str, optional): Type for credential. Defaults to None.

    Raises:

    • ValueError: name or unique_id is empty.


    Add a holder to this credential.

    Holders are the identities known to hold the credential, so several people holding keys to one shared account can be distinguished. A holder is often not an account on this host at all.

    Args:

    • identity_id (str): ID of the identity that holds the credential.

    • is_local (bool, optional): Whether the holder is an account declared on this host. Defaults to True.

    Raises:

    • OAATemplateException: identity_id is empty.


    Output function for payload.


    Something inside a host that a privilege can apply to.

    A resource is something inside a host that a privilege can apply to, such as a service or a command, rather than the host as a whole. Referred to from a grant as resource_type.id via resource_key. Created by HostNode.add_resource().

    Args:

    • name (str): Display name for resource. Required.

    • unique_id (str): Unique identifier for resource within the resource_type. Required.

    • resource_type (str): The kind of thing this is, e.g. "service" or "command". Must not contain a "." or ":" character. Required.

    Attributes:

    • resource_key (str): The resource_type.id identifier a grant uses to refer to this resource.

    Raises:

    • ValueError: name, unique_id or resource_type is empty.

    • OAATemplateException: resource_type contains a "." or ":" character.


    The resource_type.id identifier a grant uses to refer to this resource.


    Set a custom property value for the resource.

    Property name must be defined for the fleet's resources before calling set_property.

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property name is not defined.


    Output function for payload.


    A privilege defined once on the fleet and referenced by name wherever it is granted.

    Names are supplied by the connector rather than fixed by Veza. Created by HostProvider.add_privilege().

    Args:

    • name (str): Name grants refer to

    • privilege_type (list[OAAPermission]): Canonical access types this privilege confers

    • description (str, optional): Description for privilege. Defaults to None.

    Raises:

    • ValueError: name is empty.

    • OAATemplateException: A privilege_type entry is not an OAAPermission.


    Output function for payload.


    Model for defining custom properties for a Host fleet's hosts, users, groups and resources.

    Property definitions define the names for additional entity properties and the expected type. Credentials have no custom properties.

    Attributes:

    • host_properties (dict): property definitions for hosts

    • user_properties (dict): property definitions for users

    • group_properties (dict): property definitions for groups







    Check property name for valid characters

    Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.

    Args:

    • name (str): name of property to validate

    Raises:

    • OAATemplateException: Name is not a string

    • OAATemplateException: Name contains invalid characters or does not start with a letter

    tenant
    user
    group
    incremental updates
    Custom Properties
    incremental updates
    Custom Properties
    incremental updates
    Custom Properties
    incremental updates
    details (list, optional): list of additional details for error. Defaults to None.

    token (str, optional): Legacy parameter name for API key. Defaults to None.

    options: (dict, optional): Additional arguments to be included with provider create call to Veza. Defaults to None.

    (dict | None, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.
    options
    (dict | None, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.
    save_json (bool, optional): Save the JSON payload to a local file before push. Defaults to False.
  • create_provider (bool, optional): Create a new Provider if Provider does not already exists. Defaults to False.

  • options (dict, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.

  • save_json (bool, optional): Save the OAA JSON payload to a local file before push. Defaults to False.
  • options (dict, optional): Additional dictionary of key/values to be included in push API call. Defaults to None.

  • function main

    class OAAClientError

    method __init__

    class OAAResponseError

    method __init__

    class OAAConnectionError

    method __init__

    class OAAClient

    method __init__

    method add_query_report

    method api_delete

    method api_get

    method api_patch

    method api_post

    method api_put

    method create_data_source

    method create_datasource

    method create_provider

    method create_query

    method create_report

    method datasource_push

    method datasource_push_parts

    method delete_data_source

    method delete_provider

    method delete_query

    method delete_report

    method get_data_source

    method get_data_sources

    method get_provider

    method get_provider_by_id

    method get_provider_list

    method get_queries

    method get_query_by_id

    method get_report_by_id

    method get_reports

    method push_application

    method push_metadata

    method update_provider_icon

    method update_provisioning_status

    method update_report

    method update_user_agent

    class OAARetry

    method __init__

    privileges (dict[HostPrivilegeDefinition]): Dictionary of privilege definitions, referenced by name from grants

  • property_definitions (HostPropertyDefinitions): Custom property names and types for the fleet

  • identity_provider_types (list[str], optional): Which kinds of identity provider may be searched when resolving the identities this submission refers to. Values must be one of IdPProviderType. Absent or empty means all of them. Defaults to None.
    identity_provider_types (list[str], optional): Which kinds of identity provider may be searched when resolving identities this submission refers to. Values must be one of IdPProviderType. Defaults to None.

    property_definitions (HostPropertyDefinitions, optional): Property definitions structure for the fleet. Defaults to None.

    users (dict[HostUser]): Dictionary of HostUser instances
  • groups (dict[HostGroup]): Dictionary of HostGroup instances

  • credentials (dict[HostCredential]): Dictionary of HostCredential instances

  • resources (dict[HostResource]): Dictionary of HostResource instances, keyed by resource_type.id

  • identity_to_privileges (dict): Dictionary of grants, one per principal per set of things the privileges apply to

  • assumes_user (str, optional): ID of the account on this host this credential authenticates as. Defaults to None.
  • created_at (str, optional): RFC3339 timestamp. Defaults to None.

  • last_used_at (str, optional): RFC3339 timestamp. Defaults to None.

  • is_active (bool, optional): Defaults to None.

  • can_expire (bool, optional): Defaults to None.

  • expires_at (str, optional): RFC3339 timestamp. Defaults to None.

  • privileges (list, optional): Privilege names granted, each of which must have been defined on the provider with HostProvider.add_privilege(). An entry may be a bare name (str), or a dict carrying a name key where something needs to be said about how the privilege is held, such as {"name": "sudo", "no_password": True}. Defaults to None.

  • apply_to_host (bool, optional): Whether these privileges apply to the host itself. Defaults to None, in which case they apply to the host when no resources are given, and to the resources alone when some are.

  • resources (list, optional): Resources inside the host these privileges also apply to. Accepts HostResource instances or "resource_type.id" strings. Defaults to None.

  • is_local (bool, optional): True for a group defined on the host itself. False for a directory group granted access without a local definition. Defaults to True.
  • identities (list[str], optional): The identities in an identity provider this group corresponds to. Required when is_local is False. Defaults to None.

  • is_local (bool, optional): True for an account configured on the host itself. False for a network user granted access without a local account. Defaults to True.

  • identity_type (HostIdentityType, optional): Whether this account stands for a person. Absent means human. Defaults to None.

  • is_active (bool, optional): Defaults to None.

  • last_login_at (str, optional): RFC3339 timestamp of the account's last login to this host. Defaults to None.

  • is_local (bool, optional): Defaults to True.
  • identity_type (HostIdentityType, optional): Defaults to None.

  • is_active (bool, optional): Defaults to None.

  • last_login_at (str, optional): RFC3339 timestamp. Defaults to None.

  • property_definitions (CaseInsensitiveDict, optional): Property definitions for the host's users. Defaults to None.

  • is_local (bool, optional): Defaults to True.
  • identities (list[str], optional): The identities in an identity provider this group corresponds to. Defaults to None.

  • property_definitions (CaseInsensitiveDict, optional): Property definitions for the host's groups. Defaults to None.

  • assumes_user (str, optional): ID of the account on this host this credential authenticates as. Defaults to None.
  • created_at (str, optional): RFC3339 timestamp. Defaults to None.

  • last_used_at (str, optional): RFC3339 timestamp. Defaults to None.

  • is_active (bool, optional): Defaults to None.

  • can_expire (bool, optional): Defaults to None.

  • expires_at (str, optional): RFC3339 timestamp. Defaults to None.

  • property_definitions (CaseInsensitiveDict, optional): Property definitions for the host's resources. Defaults to None.
    resource_properties (dict): property definitions for resources

    method __init__

    method add_environment

    method add_host

    method add_privilege

    method get_payload

    class HostEnvironment

    method __init__

    method to_dict

    class HostNode

    method __init__

    method add_credential

    method add_grant

    method add_group

    method add_resource

    method add_user

    method set_property

    method to_dict

    class HostUser

    method __init__

    method add_group

    method set_property

    method to_dict

    class HostGroup

    method __init__

    method add_member_group

    method set_property

    method to_dict

    class HostCredential

    method __init__

    method add_holder

    method to_dict

    class HostResource

    method __init__

    property resource_key

    method set_property

    method to_dict

    class HostPrivilegeDefinition

    method __init__

    method to_dict

    class HostPropertyDefinitions

    method __init__

    method define_group_property

    method define_host_property

    method define_resource_property

    method define_user_property

    method to_dict

    method validate_name

    main()
    __init__(
        error: 'str',
        message: 'str',
        status_code: 'int' = None,
        details: 'list' = None
    ) → None
    __init__(*args, **kwargs)
    __init__(
        error: 'str',
        message: 'str',
        status_code: 'int' = None,
        details: 'list' = None
    ) → None
    __init__(
        url: 'str' = None,
        api_key: 'str' = None,
        username: 'str' = None,
        token: 'str' = None
    )
    add_query_report(report_id: 'str', query_id: 'str') → dict
    api_delete(api_path: 'str', params: 'dict' = None) → dict
    api_get(api_path: 'str', params: 'dict' = None) → list | dict
    api_patch(api_path: 'str', data: 'dict', params: 'dict' = None) → dict
    api_post(api_path: 'str', data: 'dict', params: 'dict' = None) → list | dict
    api_put(api_path: 'str', data: 'dict', params: 'dict' = None) → list | dict
    create_data_source(
        name: 'str',
        provider_id: 'str',
        options: 'dict | None' = None
    ) → dict
    create_datasource(name, provider_id)
    create_provider(
        name: 'str',
        custom_template: 'str',
        base64_icon: 'str' = '',
        options: 'dict | None' = None
    ) → dict
    create_query(query: 'dict') → dict
    create_report(report: 'dict') → dict
    datasource_push(
        provider_id: 'str',
        data_source_id: 'str',
        json_data: 'str',
        options: 'dict | None' = None
    ) → dict
    datasource_push_parts(
        provider_id: 'str',
        data_source_id: 'str',
        json_data: 'str',
        options: 'dict | None' = None,
        **configs
    ) → dict
    delete_data_source(data_source_id: 'str', provider_id: 'str') → dict
    delete_provider(provider_id: 'str') → dict
    delete_query(id: 'str', force: 'bool' = False) → dict
    delete_report(id: 'str') → dict
    get_data_source(name: 'str', provider_id: 'str') → dict
    get_data_sources(provider_id: 'str') → list[dict]
    get_provider(name: 'str') → dict
    get_provider_by_id(provider_id: 'str') → dict
    get_provider_list() → list[dict]
    get_queries(include_inactive_queries: 'bool' = True) → list[dict]
    get_query_by_id(id: 'str') → dict
    get_report_by_id(id: 'str', include_inactive_queries: 'bool' = True) → dict
    get_reports(
        include_inactive_reports: 'bool' = True,
        include_inactive_queries: 'bool' = True
    ) → list[dict]
    push_application(
        provider_name: 'str',
        data_source_name: 'str',
        application_object: 'CustomApplication | CustomIdPProvider | EntityEnrichment',
        save_json: 'bool' = False,
        create_provider: 'bool' = False,
        options: 'dict | None' = None
    ) → dict
    push_metadata(
        provider_name: 'str',
        data_source_name: 'str',
        metadata: 'dict',
        save_json: 'bool' = False,
        options: 'dict | None' = None
    ) → dict
    update_provider_icon(provider_id: 'str', base64_icon: 'str') → None
    update_provisioning_status(provider_id: 'str', provisioning: 'bool') → None
    update_report(report_id: 'str', report: 'dict') → dict
    update_user_agent(extra: 'str' = '') → None
    __init__(backoff_max=30, **kwargs) → None
    __init__(host_type: 'str') → None
    add_environment(
        unique_id: 'str',
        name: 'str',
        description: 'str' = None,
        identity_provider_types: 'List[str]' = None
    ) → HostEnvironment
    add_host(name: 'str', unique_id: 'str', environment_id: 'str' = None) → HostNode
    add_privilege(
        name: 'str',
        privilege_type: 'List[OAAPermission]',
        description: 'str' = None
    ) → HostPrivilegeDefinition
    get_payload() → dict
    __init__(
        unique_id: 'str',
        name: 'str',
        description: 'str' = None,
        identity_provider_types: 'List[str]' = None
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        environment_id: 'str' = None,
        property_definitions: 'HostPropertyDefinitions' = None
    ) → None
    add_credential(
        name: 'str',
        unique_id: 'str',
        credential_type: 'str' = None,
        assumes_user: 'str' = None,
        created_at: 'str' = None,
        last_used_at: 'str' = None,
        is_active: 'bool' = None,
        can_expire: 'bool' = None,
        expires_at: 'str' = None
    ) → HostCredential
    add_grant(
        principal_id: 'str',
        grantee_type: 'HostGranteeType',
        is_local: 'bool' = True,
        privileges: 'list' = None,
        apply_to_host: 'bool' = None,
        resources: 'list' = None
    ) → None
    add_group(
        name: 'str',
        unique_id: 'str',
        group_type: 'str' = None,
        is_local: 'bool' = True,
        identities: 'List[str]' = None
    ) → HostGroup
    add_resource(name: 'str', unique_id: 'str', resource_type: 'str') → HostResource
    add_user(
        name: 'str',
        unique_id: 'str',
        identities: 'List[str]' = None,
        is_local: 'bool' = True,
        identity_type: 'HostIdentityType' = None,
        is_active: 'bool' = None,
        last_login_at: 'str' = None
    ) → HostUser
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        identities: 'List[str]' = None,
        is_local: 'bool' = True,
        identity_type: 'HostIdentityType' = None,
        is_active: 'bool' = None,
        last_login_at: 'str' = None,
        property_definitions=None
    ) → None
    add_group(group_id: 'str') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        group_type: 'str' = None,
        is_local: 'bool' = True,
        identities: 'List[str]' = None,
        property_definitions=None
    ) → None
    add_member_group(group_id: 'str', is_local: 'bool' = True) → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        credential_type: 'str' = None,
        assumes_user: 'str' = None,
        created_at: 'str' = None,
        last_used_at: 'str' = None,
        is_active: 'bool' = None,
        can_expire: 'bool' = None,
        expires_at: 'str' = None
    ) → None
    add_holder(identity_id: 'str', is_local: 'bool' = True) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str',
        resource_type: 'str',
        property_definitions=None
    ) → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        privilege_type: 'List[OAAPermission]',
        description: 'str' = None
    ) → None
    to_dict() → dict
    __init__() → None
    define_group_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_host_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_resource_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_user_property(name: 'str', property_type: 'OAAPropertyType') → None
    to_dict() → dict
    validate_name(name: 'str') → None

    IdP

    Classes for constructing an OAA JSON payload for Custom IDP

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • PROPERTY_NAME_REGEX


    class IdPEntityType

    IdP entity types.


    class CustomIdPProvider

    CustomIdPProvider class for modeling Identity Providers (IdP) using OAA Custom Identity Provider Template.

    CustomIdPProvider class consists of IdP domain information, user, group and external associations for identities like AWS Roles.

    Classes uses dictionaries to track most components, dictionaries are all keyed by string of the entity name

    Args:

    • name (str): Name of IdP

    • idp_type (str): Type descriptor for IdP, can be unique or share across multiple IdP e.g. ldap, IPA

    • domain (str): IdP domain name

    Attributes:

    • name (str): Name of custom IdP

    • idp_type (str): Type for IdP

    • description (str): Description for IdP

    • domain


    summary

    Args:

    • id (str): description

    • name (str): description

    Raises:

    Returns:

    • CustomIdPApp: description


    Add group to IdP.

    Arguments:

    • name (str): primary ID for group

    • full_name (str): optional display name for group

    • identity (str): optional unique identifier for group, if None name is used as identity


    Add user to IdP

    if no identity is set name will be used as identity

    Arguments:

    • name (str): primary ID for user

    • full_name (str): optional full name for display

    • email (str): optional email for user

    Returns: CustomIdPUser


    Return formatted payload as dictionary for JSON conversion and upload


    Create and set the identity mapping configuration.

    Initializes the identity_mapping_configuration attribute with a new IdentityMappingConfigurationSubmission instance and returns it for further configuration.

    Returns:

    • IdentityMappingConfigurationSubmission: The identity mapping configuration.


    Domain model for Custom IdP provider.

    Args:

    • name (str): domain name

    Attributes:

    • name (str): domain name


    Add a new tag to IdP Domain.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set custom property value for domain.

    Property name must be defined for domain before calling set_property(). See example below and IdPPropertyDefinitions.define_domain_property for more information.

    Args:

    • property_name (str): Name of property

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_domain_property(name="my_property", property_type=OAAPropertyType.STRING) >>> idp.domain.set_property(property_name="my_property", property_value="domain property value")


    Output function for payload.


    Types of identities for permission mapping.


    User model for CustomIdPProvider.

    Args:

    • name (str): username for identity

    • email (str): primary email for user

    • full_name (str): Display name for user

    Attributes:

    • name (str): username for identity

    • email (str): primary email for user

    • full_name (str): display name for user


    Create App assignment for user

    Args:

    • id (str): ID of App assignment, must be unique for user

    • name (str): Name of assignment

    • app_id (str): App ID, must exist in list of Apps for IDP

    Raises:

    • OAATemplateException: Duplicate assignment ID

    • OAATemplateException: Unknown assignment property name


    Add AWS Roles to list of roles user can assume by ARN.

    Args:

    • arns (list): list of role ARNs as strings that the user is allowed to assume


    Add user to group(s) by group name

    Args:

    • group_identities (list): list of strings for group identities to add user to


    Add a new tag to IdP User.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set custom property value for user.

    Property name must be defined for users before calling set_property(). See example below and IdPPropertyDefinitions.define_user_property for more information.

    Args:

    • property_name (str): Name of property

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = idp.add_user(name="User 1") >>> user1.set_property("my_property", "user1 value")


    Set an source external identity for user.

    • source_identity will connect CustomIdP user to a Veza graph IdP user.

    • provider_type limits scope for finding matching IdP identities

    • search all providers with IdPProviderType.ANY.

    Args:

    • identity (str): Unique Identity of the source identity

    • provider_type (IdPProviderType): Type for provider to match source identity from


    Function to prepare user entity for payload


    Group model for CustomIdPProvider.

    Args:

    • name (str): name of group

    • full_name (str): optional full name for group

    • identity (str): optional identifier for group if name is not reference identifier

    Parameters:

    • name (str): name of group

    • full_name (str): optional full name for group

    • identity (str): optional identifier for group, if None name is used as identity


    Create App assignment for group

    Args:

    • id (str): ID of App assignment, must be unique for group

    • name (str): Name of assignment

    • app_id (str): App ID, must exist in list of Apps for IDP

    Raises:

    • OAATemplateException: Duplicate assignment ID

    • OAATemplateException: Unknown assignment property name


    Add AWS Roles to list of roles group members can assume by ARN.

    Args:

    • arns (list): list of role ARNs as strings that the group members are allowed to assume


    Add group to group(s) by group name

    Adds current group to another parent group by the group identifier

    Args:

    • group_identities (list): list of strings for group identities to add group to


    Add a new tag to IdP Group.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set custom property value for group.

    Property name must be defined for groups before calling set_property(). See example below and IdPPropertyDefinitions.define_group_property for more information.

    Args:

    • property_name (str): Name of property

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_group_property(name="my_property", property_type=OAAPropertyType.STRING) >>> group1 = idp.add_group(name="Group 1") >>> group1.set_property("my_property", "group1 value")


    Set an source external identity for group.

    • source_identity will connect CustomIDP group to a Veza graph IdP group.

    • provider_type limits scope for finding matching IdP group identities

    • search all providers with IdPProviderType.ANY.

    Args:

    • identity (str): Unique Identity of the source group

    • provider_type (IdPProviderType): Type for provider to match source identity from


    Function to prepare user entity for payload.


    App model for CustomIdPProvider

    Args:

    • id (str): ID for App, must be unique

    • name (str): Name for App

    • property_definitions (IdPPropertyDefinitions, optional): Custom property definitions, required to set custom properties. Defaults to None.

    Attributes:

    • id (str): ID for App, must be unique

    • name (str): Name for App

    • description (str): Description property for App


    Add AWS Roles to list of roles App can assume by ARN. Any Users or Groups assigned to the App are represented as being able to assume the roles.

    Args:

    • arns (list): list of role ARNs as strings that the user is allowed to assume


    Add a new tag to IdP User.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set custom property value for app.

    Property name must be defined for app before calling set_property(). See example below and IdPPropertyDefinitions.define_app_property for more information.

    Args:

    • property_name (str): Name of property

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example: idp = CustomIdPProvider(name="Example IdP", idp_type="example", domain="example.com") >>> idp.property_definitions.define_app_property(name="my_property", property_type=OAAPropertyType.STRING) >>> app1 = idp.add_app(id="app1", ="App 1") >>> app1.set_property("my_property", "app1 value")



    Model for defining custom properties for CustomIdPProvider and its entities (users, groups, domain).

    Property definitions define the names for additional entity properties and the expected type.

    Attributes:

    • domain_properties (dict): property definitions for IdP Domain

    • user_properties (dict): property definitions for IdP users

    • group_properties (dict): property definitions for IdP groups


    Define an app assignment custom property

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Define an app custom property

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Define a domain custom property.

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Define a group custom property.

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Define a user custom property.

    Args:

    • name (str): name of property

    • property_type (OAAPropertyType): type for property


    Returns custom IdP property definitions.


    Validate that a property name has been defined for a given IdP entity.

    Raises exception if property name has not been previously defined for entity

    Args:

    • property_name (str): name of property to validate

    • entity_type (str): type of entity custom property is for (domain, users, groups)

    Raises:

    • OAATemplateException: If property name is not defined

    description (str, optional): Description for IdP. Defaults to None.
    (CustomIdPDomain): Domain model, created with domain name at init
  • users (dict[CustomIdPUser]): Dictionary of CustomIdPUser class instances

  • groups (dict[CustomIdPGroup]): Dictionary of CustomIdPGroup class instances

  • property_definitions (IdPPropertyDefinitions): Custom Property definitions for IdP instance

  • identity_mapping_configuration (IdentityMappingConfigurationSubmission): Identity mapping configuration, set via set_identity_mapping_configuration().

  • identity
    (str): optional unique identifier for user, if None name is used as identity
    identity
    (str): unique identifier for user (may be same as username or email, or another unique ID like employee number)
    identity
    (str): unique identifier for user (may be same as username or email, or another unique ID like employee number)
  • department (str): department name for user

  • is_active (bool): if user is active, defaults to None

  • is_guest (bool): if user is a guest type user, defaults to None

  • manager_id (str, optional): CustomIdPUser.identity of manager, defaults to None

  • identity_type (IdPUserIdentityType, optional): Identity type for user (HUMAN, NONHUMAN), defaults to HUMAN if not set.

  • assignment_properties
    (Optional[dict], optional): Optional custom properties to set. Property names must be defined first. Defaults to None.
    is_security_group (bool): Property for group, defaults to None (unset)
    assignment_properties
    (Optional[dict], optional): Optional custom properties to set. Property names must be defined first. Defaults to None.

    method __init__

    method add_app

    method add_group

    method add_user

    method get_payload

    method set_identity_mapping_configuration

    class CustomIdPDomain

    method __init__

    method add_tag

    method set_property

    method to_dict

    class IdPUserIdentityType

    class CustomIdPUser

    method __init__

    method add_app_assignment

    method add_assumed_role_arns

    method add_groups

    method add_tag

    method set_property

    method set_source_identity

    method to_dict

    class CustomIdPGroup

    method __init__

    method add_app_assignment

    method add_assumed_role_arns

    method add_groups

    method add_tag

    method set_property

    method set_source_identity

    method to_dict

    class CustomIdPApp

    method __init__

    method add_assumed_role_arns

    method add_tag

    method set_property

    method to_dict

    class IdPPropertyDefinitions

    method __init__

    method define_app_assignment_property

    method define_app_property

    method define_domain_property

    method define_group_property

    method define_user_property

    method to_dict

    method validate_property_name

    __init__(
        name: 'str',
        idp_type: 'str',
        domain: 'str',
        description: 'str' = None
    ) → None
    add_app(id: 'str', name: 'str') → CustomIdPApp
    add_group(
        name: 'str',
        full_name: 'str' = None,
        identity: 'str' = None
    ) → CustomIdPGroup
    add_user(
        name: 'str',
        full_name: 'str' = None,
        email: 'str' = None,
        identity: 'str' = None
    ) → CustomIdPUser
    get_payload() → dict
    set_identity_mapping_configuration() → IdentityMappingConfigurationSubmission
    __init__(
        name: 'str',
        property_definitions: 'IdPPropertyDefinitions' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        email: 'str' = None,
        full_name: 'str' = None,
        identity: 'str' = None,
        property_definitions: 'IdPPropertyDefinitions' = None
    ) → None
    add_app_assignment(
        id: 'str',
        name: 'str',
        app_id: 'str',
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_assumed_role_arns(arns: 'List[str]') → None
    add_groups(group_identities: 'List[str]') → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    set_source_identity(identity: 'str', provider_type: 'IdPProviderType') → None
    to_dict() → dict
    __init__(
        name: 'str',
        full_name: 'str' = None,
        identity: 'str' = None,
        property_definitions: 'IdPPropertyDefinitions' = None
    ) → None
    add_app_assignment(
        id: 'str',
        name: 'str',
        app_id: 'str',
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_assumed_role_arns(arns: 'List[str]') → None
    add_groups(group_identities: 'List[str]') → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    set_source_identity(identity: 'str', provider_type: 'IdPProviderType') → None
    to_dict() → None
    __init__(
        id: 'str',
        name: 'str',
        property_definitions: 'IdPPropertyDefinitions' = None
    ) → None
    add_assumed_role_arns(arns: 'List[str]') → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__() → None
    define_app_assignment_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_app_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_domain_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_group_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_user_property(name: 'str', property_type: 'OAAPropertyType') → None
    to_dict() → dict
    validate_property_name(property_name: 'str', entity_type: 'str') → None

    OAA Push API

    Methods for working with Custom Data Providers and Sources

    This document provides a basic overview of the API requests for creating and updating an OAA data source. These steps and API calls can be adapted for your client or programming language of choice. You can also use the oaaclient Python module to handle Veza authentication, register the data source, and push the populated template.

    Overview

    While registering sources and pushing authorization metadata with Open Authorization API is relatively straightforward, it is important to understand how Veza organizes custom providers and data sources as endpoints:

    • You will first register a new custom application provider with a POST request to /api/providers/custom (specifying the app name and template).

      • The determines the type of entities the provider supports (application, identity_provider, or hris).

    • Each custom provider can have one or more data sources (such as different instances or domains), generated using .

      • The populated template can describe additional resources and sub-resources, such as individual databases, repositories, or views.

    • You can for each custom data source.

    • All custom data sources are shown on the Configuration > Apps & Data Sources menu, and can be retrieved using .

    You should typically name the provider based on the generic application provider (such as GitHub) and the data source after the top-level instance (such as GitHub - Organization). See the for more information about parsing and identifying entities using metadata from the source application.

    Your requests will need to include a Veza API Key. For OAA APIs, using a is recommended. Provide it as the bearer auth token in the header of each request, for example:

    Follow best practices for managing API keys: Do not save credentials in connector code. Consider using a secrets manager to securely store API keys and make them available at run time.

    To add a custom application, you will need to:

    • Create a new custom provider and data source.

    • push the entity and authorization data in a JSON payload.

    Use to register a new top-level custom provider. The custom_template determines what kind of entities you can push to the provider.

    Custom Application provider

    This is a common configuration with broad support for modeling applications with local identities, resources, and authorization:

    Custom Application with SCIM lifecycle management

    If your application exposes SCIM 2.0 endpoints, it can support automated provisioning and deprovisioning through :

    Custom Application with REST lifecycle management

    For applications that expose custom REST APIs (but not SCIM) for user provisioning. Veza sends REST requests to the application's endpoints through the Insight Point, which must have network access to the target application:

    Custom Identity Provider

    This template is for modeling custom or unsupported identity providers as a source of users and groups:

    Identities and groups in the custom provider can be mapped to local accounts in other systems, and assigned as entity owners. Custom IdPs can also be used as a source of identity for Provisioning Policies.

    HRIS Provider

    This template is intended to model HR information systems. Set provisioning to true to use the HRIS as a system of record for Provisioning Policies:

    Provider creation response

    All provider creation requests return the Provider ID, which you will need to create and manage data sources:

    Provider creation fields

    Field
    Type
    Required
    Description

    Using the Python SDK

    The oaaclient SDK provides create_provider() with an options parameter for advanced fields:

    Each provider needs at least one data source. Create one with

    The response will include the data source ID:

    • Datasources should be unique to the data collected by an OAA integration instance. For example, if an application has a "prod" and "dev" instance, creating a datasource for each will enable independent updates to each environment.

    • Name the data source uniquely based on the application instance to discover. Try to include the hostname or organization name in the data source. For example, don't use "GitHub" use "GitHub - Acme Inc" or "Portal - prod.corp.com"

    • Note that a provider id is required in both the request path and body.

    Once the data source and provider are active, publish the payload with . The request body must include the Provider ID and Data Source ID.

    json_data must contain the populated OAA template as a single JSON string (escaping any unsafe characters such as ").

    Specifying the Provider ID and Data Source ID, perform the same used for the initial push.

    To update an existing data source, use the operations and operations to get the provider and data source IDs.

    curl -X GET "https://$VEZA_URL/api/v1/providers/custom" \
    -H "authorization: Bearer $API_KEY"

    Template

    custom_template value

    Use case

    application

    Applications and services with users, groups, roles, resources, and permissions

    identity_provider

    Identity sources with users, groups, domains, and app assignments

    hris

    HR systems with employees, managers, and organizational groups

    curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
    -H "authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"GitHub","custom_template":"application"}'
    curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
    -H "authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Internal Portal",
      "custom_template": "application",
      "external_lifecycle_management_type": "SCIM"
    }'
    curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
    -H "authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Legacy Access System",
      "custom_template": "application",
      "external_lifecycle_management_type": "SEND_REST_PAYLOAD"
    }'
    curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
    -H "authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name":"Corporate LDAP","custom_template":"identity_provider"}'
    curl -X POST "https://$VEZA_URL/api/v1/providers/custom" \
    -H "authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Workday",
      "custom_template": "hris",
      "provisioning": true
    }'
    {
      "value": {
        "id": "a6ef8d8d-d17b-4491-a67a-635ad70f1ba9",
        "name": "GitHub",
        "custom_template": "application",
        "state": "ENABLED",
        "application_types": [],
        "resource_types": [],
        "idp_types": [],
        "schema_definition_json": "e30="
      }
    }

    name

    string

    Yes

    Provider name. Use the generic application name (e.g., "GitHub", not "GitHub - Acme").

    custom_template

    string

    Yes

    Template type: application, identity_provider, or hris.

    from oaaclient.client import OAAClient
    
    client = OAAClient(url=veza_url, token=veza_api_key)
    
    # Basic application provider
    provider = client.create_provider(name="GitHub", custom_template="application")
    
    # Application with SCIM lifecycle management
    provider = client.create_provider(
        name="Internal Portal", custom_template="application",
        options={"external_lifecycle_management_type": "SCIM"}
    )
    
    # HRIS as system of record
    provider = client.create_provider(
        name="Acme HR", custom_template="hris",
        options={"provisioning": True}
    )
    curl -X POST "https://${VEZA_URL}/api/v1/providers/custom/${PROVIDER_ID}/datasources" \
    -H 'accept: application/json' \
    -H 'authorization: Bearer '${API_KEY} \
    -d '{"id": "<PROVIDER ID>", "name":"DemoApp - Documentation Datasource"}'
    {
      "value": {
        "id": "1bd31da0-64ee-4dfe-82c9-cb9f0f2fc369",
        "name": "DemoApp - Documentation Datasource"
      }
    }
    body.json
    {
      "id": "532f6fe3-189f-4576-afdf-8913088961e4",
      "compression_type": "none",
      "data_source_id": "b6a32af6-b854-47e1-8325-e5984f78bb4d",
      "json_data": "{\"name\":\"CustomApp\",\"application_type\"...}"
    }
    curl -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:push" \
    -H 'accept: application/json' \
    -H 'authorization: Bearer '$API_KEY \
    --compressed --data-binary @body.json
    curl -X GET "https://$VEZA_URL/api/v1/providers/custom" \
    -H 'accept: application/json' \
    -H 'authorization: Bearer '$API_KEY
    curl -X GET "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID" \
    -H 'accept: application/json' \
    -H 'authorization: Bearer '$API_KEY
    curl -X POST "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID/datasources/$DATASOURCE_ID:push" \
    -H 'accept: application/json' \
    -H 'authorization: Bearer '$API_KEY \
    --compressed --data-binary @payload.json

    Authentication

    First Run

    Create a Custom Provider

    Unlike SCIM mode, SEND_REST_PAYLOAD does not require an OAA connector definition. REST endpoints, HTTP methods, authentication, and payloads are configured in the Provisioning Policy. The Insight Point associated with the data source executes the REST calls.

    • Name the provider generically after the application or SaaS provider. Use the same provider for all data sources for that application.

    • If you are creating providers dynamically, your OAA integration should check if the provider and data source exist before creating a new one.

    Create a Data Source for the Provider

    Push data source metadata

    Get Custom Providers

    Get Custom Data Sources

    Update Custom Data Source

    template
    Create Datasource
    push authorization metadata
    List Custom Provider Datasources
    Best Practices
    Team API key
    Create OAA Custom Provider
    Veza Lifecycle Management
    Create Custom Provider Datasource
    Push Custom Provider Datasource
    post operation
    List Provider
    List Datasources

    external_lifecycle_management_type

    string

    No

    Enable lifecycle management: SCIM (standard SCIM 2.0 protocol) or SEND_REST_PAYLOAD (custom REST calls via Insight Point). Only for application template.

    provisioning

    boolean

    No

    Set to true to use as system of record for Lifecycle Management. Primarily for hris template.

    Custom Application
    Custom Identity Provider
    HRIS

    Custom Identity Provider

    Template for pushing IdP domain, user, and group metadata

    Use this template to model authorization metadata for custom identity providers using the Open Authorization API.

    This document includes an example template and notes for designing and publishing a model of your IdP.

    • domain

    • users

    • groups

    A can define additional properties, used to add supplemental metadata to entities in the payload.

    Veza will handle federated identities just as those in supported IdPs such as Okta or Entra ID, enabling search and access review for OAA entities alongside the rest of your data catalog.

    The metadata payload describes the Identity Provider domain, users, and groups to add to the Veza Access Graph:

    For cases where federated IdP entities are granted AWS permissions via IAM roles, the template supports defining assumable roles per-user. Binding a custom IdP user or group to an AWS role or group ARN enables Veza to parse and display the resource-level actions permitted within AWS.

    Custom IdP users and groups can be assigned permissions in other OAA applications by setting the principal type to idp in identity_to_permissions in the payload.

    For use cases where a custom IdP is federated with another identity provider user identities can be linked between the two. Authorizations granted to the user will also be granted the source identity. The link is created by providing the unique identity ID and provider type as part of the user entry.

    For provider_type the following values are accepted:

    New in Veza release 2022.2.1

    To assign an IdP user or group as the manager of any resource Veza has discovered, list the node type and node id in the entities_owned field, for example:

    When parsing the payload, resources in the data catalog will be updated with a SYSTEM_resource_managers tag to enable entitlement reviews. The owner(s) will be suggested as reviewers for Veza Workflows that target an individual named resource with the correct tag.

    Users and groups can be mapped to the identity of another user they report to. When configured, the manager will be suggested as a review for Workflow certifications where the assigned reporter is the single query target "named entity."

    are the recommended method for adding additional metadata to custom identities and resources.

    The custom_property_definition object supports separate property namespaces for each entity type:

    Field
    Description

    Additionally, can be applied to the IdP domain, users, and groups:

    Use incremental updates to remove tags: Resubmitting a payload with different tags will apply any new tags, but not remove existing ones. To remove a tag already applied to an entity, you will need to use the remove_tag operation.

    After the initial metadata push (which must contain the full payload), you can modify, add, or remove the domain, users, and groups without resubmitting other entities. An is enabled by setting "incremental_change": true in the json_data push payload, and specifying the update operation for each entity to change.

    The identity provider object models one instance of the custom IdP:

    Field
    Type
    Description

    One domain is supported for each custom IdP. Users and groups are mapped to the IdP domain, and connected in Veza Search:

    Field
    Type
    Description

    Each IdP user object contains the display name, login email, and identity, along with other identity-related properties:

    Field
    Type
    Description

    Add a group by name in the groups section of the template to enable mapping IdP users to those groups:

    Field
    Type
    Description

    IdP entities can be granted permissions on custom applications in the identity_to_permissions section of the .

    Use the apps section to define any applications used to manage access within the identity provider. Apps can be associated with users and groups to model application assignments across your organization.

    Field
    Type
    Description

    The apps payload does not accept an owners field. To assign owners to CustomIDPApp entities, see .

    Users and Groups can be assigned to an application by setting the app_assignments in the user or group.

    Field
    Type
    Description

    The steps to add a custom IdP are the same as for any other OAA provider: you will need to register the new provider and data source, and then push the domain, user, and group descriptions in a JSON payload.

    To create a new custom provider using the identity_provider template, POST the name and template type to /providers/custom:

    The response will return the custom IdP ID, which you will need when pushing the metadata payload:

    Note that the provider id is required in both the path and body of the request. The response will include the new data source ID.

    The payload file must contain the provider and data source ID, and the authorization metadata as a single string, for example:

    The identity_mapping_configuration parameter defines rules for connecting users in a custom IdP to users from other data sources in the Veza graph.

    This is useful when:

    • The connected data source does not natively support returning information about external identities

    • A correlation between IdP identities and local users can be assumed based on values like username, email, or another property value.

    The identity_mapping_configuration is a top-level property of the Custom IDP submission, and is optional. The mapping configuration can include multiple mappings to connect IDP users to users from different data source types, each based on its own mappings.

    You can update just the identity mappings without resubmitting the entire provider payload by using an incremental update. This is useful when you need to modify only the mapping configuration while leaving other provider data unchanged.

    Example curl command to apply the incremental identity mapping update:

    Field
    Type
    Description
    Field
    Type
    Description

    Supported transformations:

    • IGNORE_SPECIAL: Ignore special characters (_, -, .) when matching identities

    • IGNORE_DOMAIN: Match identities after removing domain portions (e.g., "@example.com")

    Field
    Type
    Description

    Set source_property or destination_property to TEMPLATE to match on a constructed value instead of a single property, and put the expression in the corresponding custom_source_property or custom_destination_property field. For example, {FirstInitial | LOWER}{LastName | LOWER} matches a user named John Doe against jdoe. Veza validates the expression when you submit the payload and rejects unknown transformation functions. For the available properties and functions, see .

    okta

    One Login

    one_login

    string

    Any notes to add as entity details (optional)

    domains

    Domain model

    users

    Dictionary of CustomIdPUser class instances

    groups

    Dictionary of CustomIdPGroup class instances

    incremental_change

    boolean

    When true, enables operations (optional).

    identity_mapping_configuration

    Configuration for mapping identities between IdP User and other User types from external data sources

    list

    Any tags to create and apply to the domain.

    operation

    enum

    For , the operation to use.

    groups

    string list

    Assign groups memberships by group identity (optional)

    full_name

    string

    Full name to display in Veza

    department

    string

    Department to apply as a searchable property (optional).

    is_active

    boolean

    If available, will be applied to the entity as a searchable property (optional).

    is_guest

    boolean

    If available, will be applied to the entity as a searchable property (optional).

    assumed_role_arns

    array

    AWS IAM roles that can be assumed by the IdP user, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).

    tags

    list

    Any tags to create and apply to the user.

    dynamic_properties

    Dynamic Properties

    Up to 5 attributes to apply to the user (deprecated, use instead)

    custom_properties

    Each element of the push payload can have property_values, validated against the custom_property_definition.

    manager_id

    string

    If the same as another user's identity, that user will be recommended for reviews. Entity details for the user will be updated on push to include the manager as a searchable property.

    entities_owned

    array

    If another resource is specified by entity type and entity id, a Veza tag will be created on the resource to indicate the owner.

    operation

    enum

    For , the operation to use (optional).

    source_identity

    Optionally link IdP user to user from another IdP for federation use cases.

    groups

    string list

    other custom IdP groups this group is a member of

    is_security_group

    boolean

    Sets the is security group searchable property for the entity in Veza (optional).

    tags

    Veza Tags list

    Any to create and apply to the group.

    custom_properties

    Each element of the push payload can have property_values, validated against the custom_property_definition.

    dynamic_properties

    Dynamic Properties

    Up to 5 attributes to apply to the domain. (deprecated, use instead)

    operation

    enum

    For , the operation to use (optional).

    assumed_role_arns

    array

    AWS IAM roles the group can assume, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).

    source_identity

    Optionally link the IdP group to a group from another IdP for federation use cases (optional).

    entities_owned

    array

    Resources to assign this group as manager of (optional).

    app_assignments

    array

    App assignments for this group (optional). See .

    array

    AWS IAM roles the app can assume, in the format {"identity": ["arn:aws:iam::123456789012:role/S3Access"]} (optional).

    custom_properties

    Each element of the payload can have property_values, validated against the custom_property_definition.

    tags

    Veza Tags list

    Any to create and apply to the group.

    operation

    enum

    For , the operation to use (optional).

    Each element of the payload can have property_values, validated against the custom_property_definition.

    enum

    Entities to connect: USERS (the default) connects IdP users to destination users, GROUPS connects IdP groups to destination groups, ROLE_TO_USER connects IdP roles to destination users

    property_matchers

    IdentityMappingPropertyMatchersSubmission

    List of properties to match on

    transformations

    list enum

    Optional transformations to perform on the property values, available values: ignore_special, ignore_domain

    string

    With PROPERTY or CUSTOM_PROPERTY, the destination property name to match on. With TEMPLATE, the template expression to evaluate

    {
          "name": "Custom User",
          "assumed_role_arns": {
            "identity": [
              "arn:aws:iam::123456789012:role/S3Access"
              ]
            },
        }
    {
      "name": "Custom User",
      "identity": "00001",
      "source_identity": {
        "identity": "user0001@corp.example.com",
        "provider_type": "okta"
      }
    }

    Provider

    provider_type string

    Active Directory

    active_directory

    Any

    any

    Azure AD

    azure_ad

    OAA

    custom

    Google Workspace

    google_workspace

    {
      "name": "Custom User",
      "identity": "000011",
      "entities_owned": [
        {
          "node_type": "S3Bucket",
          "id": "arn:aws:s3:::amazon-connect-53f87966654d"
        }
      ]
    }
    {
      "name": "Custom User",
      "identity": "000013",
      "manager_id": "000011"
    }

    domain_properties

    Custom property definitions for IdP domain entities.

    user_properties

    Custom property definitions for IdP user entities.

    group_properties

    Custom property definitions for IdP group entities.

    app_properties

    Custom property definitions for IdP app entities.

    app_assignment_properties

    Custom property definitions for app assignment entities.

    "tags": [
      {
        "key": "Tag1key",
        "value": "optional_Tag1Val"
      }
    ]

    name

    string

    Name to associate with the provider in Veza.

    custom_property_definition

    Custom Property Definition

    Defines the key and types for properties that can be applied to other objects in the push payload

    idp_type

    string

    Type descriptor for IdP, can be unique or share across multiple IdP (for example ldap, IPA)

    name

    string

    IdP Domain name

    custom_properties

    Custom Properties

    Each element of the push payload can have property_values, validated against the custom_property_definition.

    dynamic_properties

    Dynamic Properties

    Up to 5 attributes to apply to the domain (deprecated, use custom properties instead)

    {
          "name": "willis",
          "email": "willis@example.com",
          "identity": "000001",
          "full_name": "Charles Willis",
          "department": "Sales",
          "is_active": true,
          "is_guest": false,
          "groups": [
            {
              "identity": "everyone"
            }
          ],
          "assumed_role_arns": {
            "identity": [
              "arn:aws:iam::123456789012:role/S3Access"
              ]
          },
          "source_identity": {
            "identity": "user0001@corp.example.com",
            "provider_type": "okta"
          },
          "tags": [],
          "custom_properties": {},
          "manager_id": "string",
          "entities_owned": {
            "node_type": "S3Bucket",
            "id": "arn:aws:s3:::amazon-connect-53f87966654d"
            }
        }

    name

    string

    Primary ID for user

    email

    string

    Optional email for user

    identity

    string

    Optional unique identifier for user

    "groups": [
      {
        "name": "developers",
        "identity": "developers",
        "full_name": null,
        "is_security_group": null,
        "assumed_role_arns": {
          "identity": ["arn:aws:iam::123456789012:role/S3Access"]
        },
        "tags": [],
        "groups": [
          { "group_1_identity": "parent" },
          { "group_2_identity": "parent" }
        ],
        "custom_properties": {}
      }
    ]

    name

    string

    IdP group name.

    identity

    string

    Unique ID used for user-group assignments.

    full_name

    string

    Optional display name for group

      "apps": [
        {
          "id": "app1",
          "name": "Application 1",
          "description": "This is a sample application",
          "assumed_role_arns": [
            {
              "identity": "arn:aws:iam::1234567890:role/DevAppRole"
            }
          ],
          "custom_properties": {
            "owner_org": "engineering"
          },
          "tags": []
        }
      ]

    id

    string

    App unique identifier.

    name

    string

    IdP app name.

    description

    string

    Description for the App (optional).

        {
          "name": "willis",
          "email": "willis@example.com",
          "identity": "cwilliams",
          "groups": [
            {
              "identity": "everyone"
            }
          ],
          "custom_properties": {
            "region": "NorthAmerica",
            "is_contractor": true
          },
          "app_assignments": [
            {
              "id": "assignment1",
              "name": "Assignment",
              "app_id": "app1",
              "custom_properties": {
                "assigned_on": "2024-12-05T12:42:25+00:00"
              }
            }
          ]
        }

    id

    string

    Assignment unique identifier.

    name

    string

    Display name for the assignment.

    app_id

    string

    Unique ID of the App to assign the identity to.

    curl -X POST 'https://<veza_url>/api/v1/providers/custom' \
    -H 'authorization: Bearer <access_token>' \
    --data-binary '{"name":"SimpleIdP","custom_template":"identity_provider"}'
    {
      "value": {
        "id": "532f6fe3-189f-4576-afdf-8913088961e4",
        "name": "Simple IdP",
        "custom_template": "identity_provider",
        "state": "ENABLED",
        "application_types": [],
        "resource_types": [],
        "idp_types": []
      }
    }
    curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources' \
    -H 'authorization: Bearer <access_token>' \
    --data-binary '{"id":"532f6fe3-189f-4576-afdf-8913088961e4", "name":"SimpleDataSource"}'
    {"value":{"id":"b6a32af6-b854-47e1-8325-e5984f78bb4d","name":"SimpleDataSource"}}
    curl -X POST 'https://<veza_url>/api/v1/providers/custom/532f6fe3-189f-4576-afdf-8913088961e4/datasources/b6a32af6-b854-47e1-8325-e5984f78bb4d:push' \
    -H 'authorization: Bearer <access_token>' \
    --compressed --data-binary @payload.json
    payload.json
    {
      "id": "532f6fe3-189f-4576-afdf-8913088961e4",
      "data_source_id": "b6a32af6-b854-47e1-8325-e5984f78bb4d",
      "json_data": "{\n\"name\":\"CustomIdentityProvider\",\n\"idp_type\": ... "
    }
    {
      "identity_mapping_configuration": {
        "mappings": [
          {
            "destination_datasource_type": "OKTA",
            "property_matchers": [
              {
                "source_property": "EMAIL",
                "destination_property": "EMAIL"
              }
            ],
            "transformations": [
              "IGNORE_SPECIAL"
            ]
          },
          {
            "destination_datasource_type": "AZURE_AD",
            "property_matchers": [
              {
                "source_property": "EMAIL",
                "destination_property": "EMAIL"
              }
            ],
            "transformations": [
              "IGNORE_DOMAIN"
            ]
          },
          {
            "destination_datasource_type": "GITHUB_USERS",
            "property_matchers": [
              {
                "source_property": "EMAIL",
                "destination_property": "UNIQUE_ID"
              }
            ]
          }
        ]
      }
    }
    curl --location 'https://<veza_url>/api/v1/providers/custom/816d6e51-6d6a-4279-ba41-2e7c732be880/datasources/716026b5-4b84-4b2f-a805-b41a6ec69cf3:push' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <API_KEY>' \
    --data '{
        "id": "816d6e51-6d6a-4279-ba41-2e7c732be880",
        "data_source_id": "716026b5-4b84-4b2f-a805-b41a6ec69cf3",
        "json_data": "{\"incremental_change\":true,\"identity_mapping_configuration\":{\"operation\":\"modify\",\"mappings\":[{\"destination_datasource_type\":\"GITHUB_USERS\",\"property_matchers\":[{\"source_property\":\"EMAIL\",\"destination_property\":\"UNIQUE_ID\"}]},{\"destination_datasource_type\":\"SQL_SERVER\",\"property_matchers\":[{\"source_property\":\"EMAIL\",\"destination_property\":\"EMAIL\"}],\"transformations\":[\"IGNORE_DOMAIN\"]}]}}"
    }'

    mappings

    IdentityMappingSubmission

    List of mappings to create between IDP Users and external data sources

    operation

    enum

    For incremental updates, the operation to use.

    destination_datasource_type

    string

    Veza Type for the destination data source, GITHUB_USERS, SQL_SERVER, CUSTOM_APPLICATION

    destination_datasource_oaa_app_type

    string

    Optional specifically for mapping to OAA Custom Application to provide a specific App Type

    destination_datasources

    list

    Optional list of destinations for the mapping, each with a type and an optional oaa_app_type. Veza uses this list only when destination_datasource_type is empty; if destination_datasource_type is set, this list is ignored

    source_property

    enum

    IdP User property to match on: UNIQUE_ID, EMAIL, PROPERTY, CUSTOM_PROPERTY, or TEMPLATE

    destination_property

    enum

    Destination User property to match on. Accepts the same values as source_property

    custom_source_property

    string

    With PROPERTY or CUSTOM_PROPERTY, the source property name to match on. With TEMPLATE, the template expression to evaluate on the source

    Sample Template and Features

    Simple Custom Identity Provider
    {
      "name": "My IdP
    

    Modeling Assumable Amazon Web Services Roles

    Source Identity Assignments

    Resource Manager Assignments

    Manager Assignments

    Custom Properties and Tags

    Incremental Updates

    Custom Identity Provider definition

    IdP Domain

    IdP Users

    IdP Groups

    IdP Apps

    Creating and Updating a Custom Identity Provider

    Register a custom identity provider

    Push a data source for the custom identity provider

    Push metadata for the data source

    Identity Mapping Configuration

    Incremental Identity Mapping Updates

    Example: Incremental Identity Mapping Update

    Set "incremental_change": true and use "operation": "modify" in the identity_mapping_configuration to update mapping rules without affecting other aspects of the provider.

    {
      "incremental_change": true,
      "identity_mapping_configuration": {
        "operation": "modify",
        "mappings": [
          {
            "destination_datasource_type": "GITHUB_USERS",
            "property_matchers": [
              {
                "source_property": "EMAIL",
                "destination_property": "UNIQUE_ID"
              }
            ]
          },
          {
            "destination_datasource_type": "SQL_SERVER",
            "property_matchers": [
              {
                "source_property": "EMAIL",
                "destination_property": "EMAIL"
              }
            ],
            "transformations": [
              "IGNORE_DOMAIN"
            ]
          }
        ]
      }
    }

    Identity Mapping Configuration

    Identity Mapping Submission

    IdentityMappingPropertyMatchersSubmission

    Property values are case-sensitive and must be uppercase. Veza resolves an unrecognized value to UNIQUE_ID without returning an error, so a lowercase email matches on unique ID instead of email address. The type, mode, and transformations fields are case-insensitive.

    apps
    identity_mapping_configuration
    custom property definition
    custom application
    Custom Properties
    Veza tags
    incremental update
    incremental update
    custom app metadata payload
    Supported entity types for owner assignment
    Template Transformations

    Okta

    idp_description

    tags

    assumed_role_arns

    custom_properties

    mode

    custom_destination_property

    Secret Store

    Template for modeling secret storage systems with vaults, entries, and permissions

    Secret Store is an Early Access feature. Contact your Veza account team to enable it for your organization.

    Use this template to model secret and credential management systems using the Open Authorization API. The Secret Store template captures the authorization relationships for custom or self-hosted credential management systems that are not covered by a native Veza integration.

    The template models a hierarchical structure:

    • Secret Store - the top-level entity representing the secret management system instance

      • Permissions - define actions that identities can perform (e.g., Read, Write, Decrypt)

      • Vaults - logical containers for secrets within the store

        • Entries - individual secrets or credentials within a vault

          • Identities - optional identity mappings linking the entry to external identities

    • Identity-to-Permission Bindings - map identities to permissions on specific vaults

    A can define additional properties for the secret store, permissions, vaults, and entries.

    To use the secret store template, set the template type to secret_store when creating a new data provider:

    Organizations with custom or self-hosted privileged access management (PAM) systems can use the Secret Store template to model their credential vaults, entries, and access permissions. This example shows how to map a typical PAM structure to the Secret Store template.

    This example demonstrates key patterns for working with the template:

    • Vaults group credentials by scope. Permissions are granted at the vault level. Grouping credentials by team or system (databases, cloud keys) is the natural unit of access control.

    • allow_identity_assume indicates whether this permission grants the ability to retrieve and use a credential's actual value.

    • rotation_policy and requires_approval** are custom properties that capture PAM-specific policies useful for access reviews and compliance reporting.

    Field
    Type
    Description

    The secret store object is the top-level container for permissions, vaults, and identity mappings.

    Field
    Type
    Description

    Permissions define the actions that identities can perform on the secret store and its vaults. Permissions are referenced by name in identity-to-permission bindings.

    Field
    Type
    Description

    Vaults are logical containers for secrets within the store. Each vault has a type and can contain multiple entries.

    Field
    Type
    Description

    Entries represent individual secrets or credentials within a vault. Entries optionally include that link the credential to external identities in the authorization graph.

    Field
    Type
    Description

    To match leaked secrets found by GitHub Secret Scanning to an entry, tag the entry with the credential's identifier. See .

    When finds a leaked credential, Veza connects the leaked secret to the Secret Store entries that hold the same credential, with a Matches Credential relationship. An entry matches when it has a tag for the leaked credential's type whose value is the credential's identifier. Tag names and values aren't case-sensitive. Without the tag, an entry matches only through its key_ids. Tags are the main way to connect entries. Use key_ids when the credential's identifier is already its own field, such as a column of a CSV export, so you don't need to add it as a tag. In a , key_ids is the Key IDs attribute, and tags come from the column mapped to Tags.

    Leaked credential type
    Entry tag
    Tag value

    Veza checks for matches in this order, and stops at the first step that finds any:

    1. Each tag name for the credential type, in the order listed. For LDAP_BIND, bind_cn is checked before bind_identity, so if any entry has a matching bind_cn tag, entries with only a matching bind_identity tag aren't connected. Use the same tag name on all your entries.

    2. Entries whose key_ids include the leaked credential's identifier

    Veza connects the leaked secret to every entry found in that step. Only entries whose credential GitHub Secret Scanning finds leaked are connected, so most entries in a vault have no Matches Credential relationship. Veza correlates again after each GitHub scan and each new Secret Store upload.

    When secret_store_type is thales_ciphertrust or akeyless and an entry has no key_ids, Veza builds key_ids from these tags or custom properties of the entry. Names aren't case-sensitive, and - matches _. If an entry has key_ids, Veza uses those values as they are and builds none.

    Key IDs are the identifiers Veza compares with leaked credentials. Only values in key_ids equal to an identifier that GitHub Secret Scanning currently reports can match: an AWS access key ID, an Azure storage account name, an LDAP account name, or a SQL Server login. Key IDs built for CipherTrust keys, which are key URLs, ARNs, and aliases, don't match any of these.

    Identity mappings on vault entries link a credential to external identities in the authorization graph. When the payload is parsed, Veza creates graph edges between the vault entry and the referenced identities. See for more information.

    Field
    Type
    Description

    Identity-to-permission mappings define which identities have which permissions on which vaults. Each mapping links an identity to one or more permission assignments.

    Field
    Type
    Description

    Each permission assignment binds a set of permissions to a set of vaults for the parent identity.

    Field
    Type
    Description

    Custom properties allow you to attach additional metadata to secret store entities. Define properties in the custom_property_definition object, then set values on individual entities.

    Scope
    Description

    Property values must match their declared type. Supported types are described in .

    After the initial metadata push (which must contain the full payload), you can modify, add, or remove the secret store, permissions, vaults, entries, and identity assignments without resubmitting other entities. An is enabled by setting "incremental_change": true in the push payload, and specifying the update operation for each entity to change.

    To create the OAA provider and push data:

    1. Create the provider with the secret_store template type:

    2. Create a data source on the provider:

    3. Push the payload to the data source:

      The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json

    Updates follow the same push workflow. Veza processes the full payload and updates the Authorization Graph accordingly.

    "
    ,
    "idp_type": "custom_idp",
    "domains": [
    {
    "name": "example.com",
    "tags": [],
    }
    ],
    "users": [
    {
    "name": "m_richardson",
    "email": "mrichardson@example.com",
    "identity": "m_richardson",
    "full_name": "Michelle Richardson",
    "department": null,
    "is_active": true,
    "is_guest": false,
    "groups": [
    {
    "identity": "everyone"
    },
    {
    "identity": "developers"
    }
    ],
    "assumed_role_arns": [
    {
    "identity": "arn:aws:iam::123456789012:role/role001"
    },
    {
    "identity": "arn:aws:iam::123456789012:role/role002"
    }
    ],
    "tags": [],
    },
    {
    "name": "evargas",
    "email": "evargas@example.com",
    "identity": "evargas",
    "full_name": "Elizabeth Vargas",
    "department": null,
    "is_active": true,
    "is_guest": false,
    "groups": [
    {
    "identity": "everyone"
    },
    {
    "identity": "developers"
    },
    {
    "identity": "sec-ops"
    }
    ],
    "assumed_role_arns": [],
    "tags": [],
    },
    {
    "name": "willis",
    "email": "willis@example.com",
    "identity": "c_williams",
    "full_name": null,
    "department": null,
    "is_active": true,
    "is_guest": false,
    "groups": [
    {
    "identity": "everyone"
    }
    ],
    "assumed_role_arns": [],
    "tags": []
    }
    ],
    "groups": [
    {
    "name": "developers",
    "identity": "developers",
    "full_name": null,
    "is_security_group": null,
    "tags": []
    },
    {
    "name": "sec-ops",
    "identity": "sec-ops",
    "full_name": null,
    "is_security_group": null,
    "tags": []
    },
    {
    "name": "everyone",
    "identity": "everyone",
    "full_name": "All Company Employees",
    "is_security_group": null,
    "tags": []
    }
    ],
    "identity_mapping_configuration": {
    "mappings": [
    {
    "destination_datasource_type": "GITHUB_USERS",
    "property_matchers": [
    {
    "source_property": "EMAIL",
    "destination_property": "UNIQUE_ID"
    }
    ]
    },
    {
    "destination_datasource_type": "SQL_SERVER",
    "property_matchers": [
    {
    "source_property": "EMAIL",
    "destination_property": "EMAIL"
    }
    ],
    "transformations": [
    "IGNORE_DOMAIN"
    ]
    }
    ]
    }
    }
    IdP Domain
    IdP Users
    IdP Group
    incremental update
    Identity Mapping Configuration
    Veza Tags
    incremental updates
    Veza Tags
    custom properties
    Custom Properties
    access
    Entities Owned
    incremental updates
    Source Identity
    tags
    Custom Properties
    custom properties
    incremental updates
    Source Identity
    Entities Owned
    IdP Apps
    Custom Properties
    tags
    incremental updates
    Custom Properties
    and escapes it as a JSON string.
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"MySecretStore","custom_template":"secret_store"}'

    secret_store_type

    string

    Type descriptor for the secret store (e.g., hashicorp_vault). Applied as a searchable property. thales_ciphertrust and akeyless also turn on

    custom_property_definition

    object

    Defines custom properties for the store, permissions, vaults, and entries. See

    secret_store

    object

    The object containing all entities

    "secret_store": {
      "name": "Production Vault",
      "id": "prod-vault-001",
      "description": "Production environment secrets",
      "tags": [],
      "custom_properties": {},
      "permissions": [],
      "secret_store_vaults": [],
      "identity_to_permissions": []
    }

    name

    string

    Display name for the secret store

    id

    string

    Unique identifier. Defaults to name if not provided

    description

    string

    Description shown in Veza entity details (optional)

    "permissions": [
      {
        "name": "Read",
        "id": "perm-read",
        "resource": "secrets/*",
        "allow_identity_assume": false
      }
    ]

    name

    string

    Display name for the permission

    id

    string

    Unique identifier. Defaults to name if not provided

    resource

    string

    Resource path or pattern this permission applies to (optional)

    "secret_store_vaults": [
      {
        "name": "API Keys",
        "id": "vault-api-keys",
        "vault_type": "kv",
        "description": "API key storage",
        "tags": [],
        "custom_properties": {},
        "entries": []
      }
    ]

    name

    string

    Display name for the vault

    id

    string

    Unique identifier. Defaults to name if not provided

    vault_type

    string

    Type descriptor for the vault (e.g., kv, transit, pki). Required

    "entries": [
      {
        "name": "Stripe API Key",
        "id": "entry-stripe",
        "description": "Stripe payment processing key",
        "custom_properties": {
          "rotation_enabled": true
        },
        "identities": [
          {
            "type": "OktaUser",
            "external_id": "alice@example.com"
          }
        ]
      }
    ]

    name

    string

    Display name for the entry

    id

    string

    Unique identifier. Defaults to name if not provided

    description

    string

    Description shown in Veza entity details (optional)

    AWS_ACCESS_KEY, AWS_SECRET_ACCESS_KEY

    aws_key_id

    The AWS access key ID. A leaked secret access key matches only when its access key ID is found within a few lines of it

    AZURE_STORAGE_ACCOUNT_KEY

    azure_storage_account_name

    The Azure storage account name

    LDAP_BIND

    bind_cn or bind_identity

    The account name only, such as svc-reports, not the full distinguished name. Names with spaces can't be matched

    secret_store_type

    Tag or custom property

    Key ID

    thales_ciphertrust

    kid

    The Azure Key Vault key URL, both as is and without its version

    thales_ciphertrust

    arn

    The AWS KMS key ARN

    thales_ciphertrust

    keyid or key_id

    The AWS KMS key ID

    thales_ciphertrust

    alias

    "identities": [
      {
        "type": "OktaUser",
        "external_id": "alice@example.com"
      }
    ]

    type

    string

    The type of external identity (e.g., OktaUser, AzureADUser, AWSIAMUser)

    external_id

    string

    The external identifier for the identity (e.g., email address, ARN)

    "identity_to_permissions": [
      {
        "identity": "admin-user",
        "identity_type": "local_user",
        "permission_assignments": [
          {
            "vault": ["vault-api-keys", "vault-db-creds"],
            "permissions": ["Read", "Write"]
          }
        ]
      }
    ]

    identity

    string

    The identity ID or name

    identity_type

    string

    The type of identity (e.g., local_user)

    permission_assignments

    array

    Array of objects

    vault

    array

    List of vault IDs or names that this assignment applies to

    permissions

    array

    List of permission names granted to the identity on these vaults

    "custom_property_definition": {
      "secret_store_properties": {
        "environment": "STRING"
      },
      "permission_properties": {},
      "vault_properties": {
        "encryption_type": "STRING"
      },
      "entry_properties": {
        "rotation_enabled": "BOOLEAN"
      }
    }

    secret_store_properties

    Custom properties for the secret store entity

    permission_properties

    Custom properties for permission entities

    vault_properties

    Custom properties for vault entities

    entry_properties

    Custom properties for vault entry entities

    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"MySecretStore","custom_template":"secret_store"}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"my_secret_store_source"}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data "{\"json_data\": $(jq -Rs . payload.json)}"

    Sample Payloads

    HashiCorp Vault Example

    This example demonstrates a secret store with two vaults, permissions, vault entries with identity mappings, and identity-to-permission bindings.

    Example: Custom PAM Integration

    Custom PAM Payload

    This payload models a custom PAM system with two credential vaults, permission definitions, and identity-to-permission mappings reflecting typical DBA and platform engineer access patterns.

    Top-Level Payload

    Secret Store object

    Secret Store Properties

    Permissions

    Permission Properties

    Vaults

    Vault Properties

    Vault Entries

    Vault Entry Properties

    Leaked Secret Correlation

    Key IDs Built from Vendor Properties

    Vault Entry Identities

    Identity Properties

    Identity to Permissions

    Identity-to-Permission Properties

    Permission Assignments

    Custom Property Definitions

    Incremental Updates

    Creating and Updating a Secret Store

    custom property definition
    identity mappings
    Leaked Secret Correlation
    GitHub Secret Scanning
    CSV upload
    Custom Identity Mappings
    Custom Properties
    incremental update

    identity_mapping_configuration

    object

    Optional configuration for mapping local identities to users from external data sources

    incremental_change

    boolean

    When true, enables (optional)

    tags

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    validated against the custom_property_definition

    operation

    string

    Operation type for (optional)

    permissions

    array

    Array of objects

    secret_store_vaults

    array

    Array of objects

    identity_to_permissions

    array

    Array of mappings

    allow_identity_assume

    boolean

    Whether this permission allows identity assumption (optional)

    tags

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    operation

    string

    Operation type for (optional)

    description

    string

    Description shown in Veza entity details (optional)

    tags

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    validated against the custom_property_definition

    operation

    string

    Operation type for (optional)

    entries

    array

    Array of objects

    tags

    array

    Specify tags with a key and optional value

    custom_properties

    dictionary

    validated against the custom_property_definition

    operation

    string

    Operation type for (optional)

    identities

    array

    Array of objects (optional)

    expires_at

    timestamp

    When the credential expires, in RFC 3339 format (optional)

    credential_type

    string

    The kind of credential the entry holds, using the GitHub Secret Scanning credential types, such as AWS_ACCESS_KEY. Informational only (optional)

    key_ids

    array

    Identifiers of the credential, which can match leaked secrets with the same identifier (optional)

    key_id_kinds

    array

    A label for each value in key_ids. Must have the same number of values as key_ids (optional)

    MSSQL_SQL_LOGIN

    sql_login

    The SQL Server login

    The AWS KMS alias, without the alias/ prefix

    akeyless

    bind_identity

    The LDAP account name

    akeyless

    bind_dn

    The LDAP bind distinguished name

    akeyless

    bind_identity and ldap_host

    DOMAIN\account, where DOMAIN is the first label of ldap_host

    akeyless

    sql_login

    The SQL Server login

    akeyless

    sql_login and mssql_host

    host/login, or host:port/login when mssql_port is set

    {
      "secret_store_type": "hashicorp_vault",
      "custom_property_definition": {
        "secret_store_properties": {
          "environment": "STRING"
        },
        "permission_properties": {},
        "vault_properties": {
          "encryption_type": "STRING"
        },
        "entry_properties": {
          "rotation_enabled": "BOOLEAN"
        }
      },
      "secret_store": {
        "name": "Production Vault",
        "id": "prod-vault-001",
        "description": "Production environment secrets",
        "tags": [
          {
            "key": "department",
            "value": "engineering"
          }
        ],
        "custom_properties": {
          "environment": "production"
        },
        "permissions": [
          {
            "name": "Read",
            "id": "perm-read",
            "resource": "secrets/*",
            "allow_identity_assume": false
          },
          {
            "name": "Write",
            "id": "perm-write",
            "resource": "secrets/*",
            "allow_identity_assume": true
          }
        ],
        "secret_store_vaults": [
          {
            "name": "API Keys",
            "id": "vault-api-keys",
            "vault_type": "kv",
            "description": "API key storage",
            "tags": [
              {
                "key": "category",
                "value": "api-credentials"
              }
            ],
            "custom_properties": {
              "encryption_type": "AES-256"
            },
            "entries": [
              {
                "name": "Stripe API Key",
                "id": "entry-stripe",
                "description": "Stripe payment processing key",
                "custom_properties": {
                  "rotation_enabled": true
                },
                "identities": [
                  {
                    "type": "OktaUser",
                    "external_id": "alice@example.com"
                  }
                ]
              }
            ]
          },
          {
            "name": "Database Credentials",
            "id": "vault-db-creds",
            "vault_type": "kv",
            "description": "Database connection credentials",
            "custom_properties": {
              "encryption_type": "AES-256"
            },
            "entries": [
              {
                "name": "PostgreSQL Admin",
                "id": "entry-postgres",
                "description": "PostgreSQL admin credentials",
                "custom_properties": {
                  "rotation_enabled": true
                }
              }
            ]
          }
        ],
        "identity_to_permissions": [
          {
            "identity": "admin-user",
            "identity_type": "local_user",
            "permission_assignments": [
              {
                "vault": [
                  "vault-api-keys",
                  "vault-db-creds"
                ],
                "permissions": [
                  "Read",
                  "Write"
                ]
              }
            ]
          },
          {
            "identity": "developer-user",
            "identity_type": "local_user",
            "permission_assignments": [
              {
                "vault": [
                  "vault-api-keys"
                ],
                "permissions": [
                  "Read"
                ]
              }
            ]
          }
        ]
      }
    }
    {
      "secret_store_type": "custom_pam",
      "custom_property_definition": {
        "vault_properties": {
          "rotation_policy": "STRING",
          "requires_approval": "BOOLEAN"
        },
        "entry_properties": {
          "credential_type": "STRING"
        }
      },
      "secret_store": {
        "name": "ACME Internal PAM",
        "id": "pam.acme-internal.example.com",
        "description": "Production internal credential management system",
        "tags": [
          {
            "key": "environment",
            "value": "production"
          }
        ],
        "permissions": [
          {
            "name": "View",
            "id": "perm-view",
            "allow_identity_assume": false
          },
          {
            "name": "Checkout",
            "id": "perm-checkout",
            "allow_identity_assume": true
          },
          {
            "name": "Rotate",
            "id": "perm-rotate",
            "allow_identity_assume": false
          },
          {
            "name": "Manage",
            "id": "perm-manage",
            "allow_identity_assume": false
          }
        ],
        "secret_store_vaults": [
          {
            "name": "Production Databases",
            "id": "vault-prod-databases",
            "vault_type": "database",
            "description": "Privileged database credentials for production systems",
            "custom_properties": {
              "rotation_policy": "30-day",
              "requires_approval": true
            },
            "entries": [
              {
                "name": "postgres-prod-admin",
                "id": "cred-pg-admin-001",
                "description": "PostgreSQL production superuser",
                "custom_properties": {
                  "credential_type": "service_account"
                },
                "identities": [
                  {
                    "type": "AzureADUser",
                    "external_id": "dba-admin@acme.com"
                  }
                ]
              },
              {
                "name": "mysql-prod-readonly",
                "id": "cred-mysql-ro-001",
                "description": "MySQL production read-only service account",
                "custom_properties": {
                  "credential_type": "service_account"
                }
              }
            ]
          },
          {
            "name": "Cloud Platform Keys",
            "id": "vault-cloud-keys",
            "vault_type": "cloud_credentials",
            "description": "Cloud provider access keys",
            "custom_properties": {
              "rotation_policy": "90-day",
              "requires_approval": false
            },
            "entries": [
              {
                "name": "cloud-prod-admin",
                "id": "cred-cloud-admin-001",
                "description": "Production cloud IAM admin access key",
                "custom_properties": {
                  "credential_type": "access_key"
                },
                "identities": [
                  {
                    "type": "AzureADUser",
                    "external_id": "platform-eng@acme.com"
                  }
                ]
              }
            ]
          }
        ],
        "identity_to_permissions": [
          {
            "identity": "dba-admin@acme.com",
            "identity_type": "AzureADUser",
            "permission_assignments": [
              {
                "vault": ["vault-prod-databases"],
                "permissions": ["View", "Checkout"]
              }
            ]
          },
          {
            "identity": "platform-eng@acme.com",
            "identity_type": "AzureADUser",
            "permission_assignments": [
              {
                "vault": ["vault-cloud-keys"],
                "permissions": ["View", "Checkout", "Rotate"]
              },
              {
                "vault": ["vault-prod-databases"],
                "permissions": ["View"]
              }
            ]
          }
        ]
      }
    }
    Key IDs built from vendor properties
    Custom Properties
    secret store
    permission assignment
    incremental updates
    Custom Properties
    incremental updates
    permission
    vault
    identity-to-permission
    Custom Properties
    incremental updates
    Custom Properties
    incremental updates
    vault entry
    Custom Properties
    incremental updates
    identity mapping

    Custom Application

    Template for pushing custom data source entities and authorization

    Overview

    The Custom Application Template can be used to model most applications and services. It can describe many common entity types (such as users, groups, and resources), and should be the starting point for most custom connectors.

    The template has three primary elements, covered in detail in this document:

    • Applications - describes one or more application instances for the custom data source. An application may consist of any of the following entities:

      • Local Users - defines the users of the application. The local user entity can be used to store the properties of the user specific to the application (such as last_login_at) and can be linked to a source identity such as Okta or Azure AD.

      • Local Groups - defines a group of users, permissions to the application or resources can be assigned to a group.

      • Local Roles - defines a collection of permissions. A role can be used to link an identity (local user, group, or IdP) to an application or resource. An identity assigned to a role will be assigned all permissions from that role.

      • Local Access Credentials - defines API keys, tokens, certificates, or other non-human authentication methods used by applications or services.

      • Resources - for more fine grain authorization tracking resources can be used to represent components of the application that have their own authorization. Users and groups can be assigned permission or roles to resources.

        • Sub Resources - resources can additionally have sub-resources for additional levels of depth.

    • Permissions - define the applications specific permissions and map to Veza canonical permissions.

    • Identity to Permissions - Assign local and federated users and groups to permissions or roles to the application and resources.

    • Additionally, a may describe user-configured key:pair values that can be applied to entities in the payload.

    To use the generic app template, set the template type to application when creating a new data provider:

    If your custom application exposes SCIM 2.0 compliant endpoints, you can enable automated provisioning and deprovisioning through Veza Lifecycle Management and Access Requests by setting the external_lifecycle_management_type parameter to SCIM:

    This enables Veza to automate user provisioning, deprovisioning, and group membership management for your custom application. For detailed configuration and supported operations, see .

    and can be applied to most objects in the OAA payload: the application and its local_users, local_groups, local_roles and resources/sub_resources.

    Define custom properties

    In the rest of the payload, for each object that should have additional properties, add a custom_properties array containing the property keys and values:

    Use incremental updates to remove tags: Resubmitting a payload with different tags will apply any new tags, but not remove existing ones. To remove a tag already applied to an entity, you will need to use the remove_tag operation.

    Validation and Troubleshooting

    The API response will provide information for invalid data submission. You can check Veza events for updates on parsing status. Errors won't typically occur during parsing, as the metadata is validated upon push. To ensure a valid payload, you should:

    • Confirm all string fields are are valid UTF-8 strings no larger than 256 bytes.

    • Check that all required fields are present. Tags and properties are optional. You can null empty groups, roles, and other "empty" but required keys.

    • A 200 OK response may include warnings when matching IDP identities can't be found

    The OAA payload must contain at least one top-level application. To model data systems with multiple components (such as different servers or repositories), applications can have resources and sub-resources.

    You can also specify more than one application in the OAA payload, each with its own identities, permissions, roles, and resources.

    The application_typeis applied to all application resources and identities, and can be used as a filterable property in Veza search.

    Field
    Type
    Description

    Optional fields: some values in the schema are optional. When submitting a payload without a required field, an error message will help identify the issue. The following guidelines apply:

    • Any type of data in a JSON payload can be null (not set).

    • Unused optional arrays and objects should be empty {} or [].

    • Unused optional strings, numbers, and booleans should be null.

    OAA apps need to contain at least one identity, which could be a local_group, local_role, or an IdP identity. Role assignments are made in the section.

    Each application can contain one or more resources that users can access. Resources can have additional searchable properties and may contain additional sub-resources.

    Sub-resources describe additional layers of the application principals can have authorization to, and support the same properties as resources, including additionally nested sub-resources.

    An application can have any number of nested sub resources.

    Field
    Type
    Description

    * A specific resource type must have only resources with an id, or only resources without an id. When used identity_to_permissions assignments are made by the id value and name functions as a display name.

    In the system being modeled, application resources and sub-resources (such as virtual machines or Looker views) have access to other entities in the Veza Access Graph.

    If an application resource or sub-resource is able to assume the permissions of a local user, IAM role, or Enterprise application, you can specify the connections to another graph entity node_type and id:

    The following node types are currently available:

    • SnowflakeUser

    • GoogleCloudServiceAccount

    • AwsIamRole

    Applications can have local users and groups for identities. For users and groups that correlate to an external Identity Provider (for example accounts automatically provisioned by the IdP), set the value that identifies them in that provider in identities. Veza compares each value against a fixed set of attributes per provider, listed in .

    Contains any users whose profiles and authentication are handled and stored by the custom application. Local users include their group assignments and any federated identities that should be mapped to the local user:

    Field
    Type
    Description

    If the application has any groups, describe each one in the local_groups array.

    Group assignments for entities are defined in identity_to_permissions.

    Field
    Type
    Description

    *Each value must equal one of the attributes Veza compares on the identity provider. See .

    Local roles define collections of local permissions that can be assigned to multiple resources. In the applications section, roles are named and mapped to permissions. Role assignments are defined in identity_to_permissions.

    Field
    Type
    Description

    Access credentials represent API keys, tokens, certificates, or other non-human authentication methods used by applications or services.

    Field
    Type
    Description

    permissions

    Bind local permissions to the corresponding Veza canonical permission(s). Each native application permission should be included as an object, mapped to the corresponding data/non-data actions it allows.

    Canonical permission types are:

    • DataRead

    • DataWrite

    • MetadataRead

    Field
    Type
    Description

    To better model systems where roles can contain different permissions to different types of resources, permissions can apply to individual resource_types.

    • When the payload is parsed, individual permissions are created for each type of resource the permission applies to.

    • Without resource_types specified, the permission will function normally. When directly connecting principals and resources, resource_type is ignored.

    Contains an object for each local and IdP identity, and the individual permissions to applications and resources.

    • You can bind permissions to federated users and groups by providing the principal’s IDP login email or group name as the identity, and setting the identity_type to idp.

    • Permissions and role assignments can apply to the entire application or scoped to specific resources.

    • For each identity (matching a local user, group, or IdP identity), state the identity type and add the assigned permissions/roles:

    Field
    Type
    Description
    • Each identity can be either a local_user, local_role, local_group, or local_access_creds name, or the identifier of an IdP user, group, or role (email address or group name).

    • identity_type must be one of: idp

    application_permissions

    Binds the identity (IdP entity, local user, or local group) to local permission, by application and resources.

    Field
    Type
    Description

    role_assignments

    Local roles are assigned to identities in the role_assignments array. Roles can apply to the entire application or only to specific (sub) resources.

    Field
    Type
    Description

    The identity_to_permissions array defines how identities are authorized to applications and resources. Each entry maps an identity to its application permissions and/or role assignments. See the section above for field details.

    Strings and string lists intended to have constant values (enums) such as identity_type may have a default value when not set.
    AzureADEnterpriseApplication
  • TrinoUser

  • MetadataWrite
  • NonData

  • DataCreate

  • DataDelete

  • MetadataCreate

  • MetadataDelete

  • Uncategorized

  • (default),
    local_user
    ,
    local_group
    ,
    local_role
    , or
    local_access_creds
    .
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    --compressed --data-binary '{"name":"DemoApp","custom_template":"application"}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{
      "name": "MyCustomApp",
      "custom_template": "application",
      "external_lifecycle_management_type": "SCIM"
    }'
      "custom_property_definition": {
        "applications": [
          {
            "application_type": "sample",
            "application_properties": {},
            "local_user_properties": {
              "license_type": "STRING",
              "license_expires": "TIMESTAMP"
            },
            "local_group_properties": {},
            "local_role_properties": {},
            "role_assignment_properties": {},
            "access_cred_properties": {},
            "resources": []
          }
        ]
      }
          "local_users": [
            {
              "id": "001010",
              "name": "bob",
              "identities": [
                "bob@example.com"
              ],
              "groups": null,
              "is_active": true,
              "created_at": "2022-01-26T20:48:12.460Z",
              "last_login_at": null,
              "deactivated_at": null,
              "password_last_changed_at": null,
              "tags": [],
              "custom_properties": {
                "license_type": "pro",
                "license_expires": "2023-01-01T00:00:00.000Z"
              }
            }
          ]
    {
      "applications": [
        {
          "name": "Custom App",
          "application_type": "Source Control",
          "description": "Has a resource for each repository",
          "custom_properties": {},
          "tags": [],
          "owners": [],
          "local_users": [],
          "local_groups": [],
          "local_roles": [],
          "resources": []
        }
      ]
    }

    name

    string

    Identifies the app in Veza Search. Used to bind permissions to the application

    application_type

    string

    Applied to all entities within the application as a searchable property. Multiple instances of an application can share the same type

    description

    string

    Any additional notes to show in the entity details, limit 256 characters

    "resources": [
      {
        "name": "Entity1",
        "id": "Unique ID",
        "resource_type": "thing",
        "description": "Some entity in the application",
        "sub_resources": [
          {
            "name": "Child 1",
            "resource_type": "child",
            "description": "My information about resource",
            "sub_resources": [],
            "custom_properties": {},
            "tags": [],
            "owners": []
          }
        ],
        "custom_properties": {},
        "tags": [],
        "owners": []
      },
      {
        "name": "Entity2",
        "id": "Another Unique ID",
        "resource_type": "thing",
        "description": "Another entity in the application",
        "sub_resources": [],
        "custom_properties": {},
        "tags": [],
        "owners": [],
      }
    ]

    name

    string

    Resource name. Primary ID for mapping users to individual resource permissions.

    id

    string

    Optional value to use as the unique ID, instead of the resource name*.

    resource_type

    string

    Searchable label for the resource type. The application entity details in Veza will show the contained resource types as properties.

    {
      "name": "cog1",
      "resource_type": "cog",
      "connections": [
        {
          "id": "service_account@some-project.iam.gserviceaccount.com",
          "node_type": "GoogleCloudServiceAccount"
         }
      ]
    }
    "local_users": [
      {
        "id": "egray",
        "name": "Evan Gray",
        "email": "egray@example.com",
        "identities": ["egray@example.com"],
        "groups": ["contractors"],
        "is_active": true,
        "created_at": "2020-12-19T16:39:57-08:00",
        "last_login_at": "2021-11-19T14:19:30-08:00",
        "password_last_changed_at": null,
        "deactivated_at": null,
        "custom_properties": {},
        "tags": [],
        "owners": []
       }
    ]

    name

    string

    Name of the local user, shown in the Veza UI.

    id

    string

    Optional identifier to use for mapping users to groups, roles, and permissions.

    email

    string

    User email address (optional). Separate from identities, this is a display/metadata field on the user entity.

    "local_groups": [
      {
        "name": "US Contractors",
        "id": "us-contractors",
        "identities": ["user1@company.com"],
        "groups": [
          "all-contractors",
          "all-workers"
        ],
        "tags": [],
        "owners": []
      }
    ]

    name

    string

    Name of the local group. Primary ID for mapping group to permissions.

    id

    string

    Optional identifier to use for permissions mapping.

    identities

    array

    If IdP users are members of the local group, or if the local group directly maps to an IdP group, list them here.*

    "local_roles": [
        {
            "name": "administrator",
            "id": "0001",
            "permissions": ["create","destroy"]
        },
        {
            "name": "operator",
            "id": "0002",
            "permissions": ["pull", "read"],
            "tags": [],
            "owners": []
        }
    ]

    name

    string

    Name of the local role. Primary ID for mapping role to permissions.

    id

    string

    Optional identifier to use for permissions mapping.

    permissions

    array

    Permissions associated with the role. Must exist in permissions.

    "local_access_creds": [
      {
        "name": "Production API Key",
        "id": "prod-key-001",
        "created_at": "2023-01-15T08:00:00.000Z",
        "expires_at": "2024-01-15T08:00:00.000Z",
        "last_used_at": "2023-12-01T14:30:00.000Z",
        "can_expire": true,
        "is_active": true,
        "custom_properties": {},
        "tags": [],
        "owners": []
      }
    ]

    name

    string

    Name of the access credential

    id

    string

    Unique identifier for the credential

    created_at

    RFC3339 string

    When the credential was created (optional)

    "permissions": [
       {
         "name": "Admin",
         "permission_type": [
           "DataRead",
           "DataWrite",
           "MetadataRead",
           "MetadataWrite"
         ]
       },
       {
         "name": "Operator",
         "permission_type": [
           "MetadataRead",
           "DataRead"
         ]
       },
       {
         "name": "Inactive",
         "permission_type": [
           "NonData"
         ]
       }
     ]

    name

    string

    Native permission name, such as “Push” (used to bind local and IdP identities to native permissions).

    permission_type

    enum

    List of canonical privilege(s) the permission represents.

    apply_to_sub_resources

    bool

    To more accurately model applications where permissions should apply to any children of a resource, set TRUE to define the permission as inheritable. This eliminates the need to include the permission at each sub level.

    "identity_to_permissions": [
         {
           "identity": "Evan Gray",
           "identity_type": "local_user",
           "application_permissions": [
              {
               "application": "Veza AI",
               "resources": ["terraform-dev", "prod"],
               "permission": "pull"
             },
             {
               "application": "Veza AI",
               "resources": ["terraform-dev", "prod"],
               "permission": "push"
             }
           ]
         }
       ]

    identity

    string

    Principal name or email address. Maps to IdP login email or group name.

    identity_type

    string

    Sets whether the identity corresponds to an IdP identity, or is local to the application

    application_permissions

    array

    List each local permission available to the identity (must be a valid permission name from the previous section).

    {
        "identity": "idpuser@org.co",
        "identity_type": "idp",
        "application_permissions":
        [
            {
                "application": "source control",
                "resources": ["util-tools", "terraform"],
                "apply_to_application": false,
                "permission": "write"
            },
            {
                "application": "source control",
                "resources": [],
                "apply_to_application": true,
                "permission": "read"
            }
        ]
    }

    application

    string

    Maps to an application name from the first section. Must exist in applications

    resources

    array

    List of application resource or sub-resource names to apply the permission. Must exist in applications

    apply_to_application

    boolean

    Set to true to model environments where permissions apply to the top-level application as well as its resources.

    {
        "identity": "john_smith",
        "identity_type": "local_user",
        "role_assignments":[
            {
                "application": "custom application",
                "role": "administrator",
                "apply_to_application": true,
                "resources": []
            },
            {
                "application": "custom application",
                "role": "ops",
                "apply_to_application": false,
                "resources": ["oaa-vm-1"]
            }
        ]
    }

    application

    string

    The application where the role applies. Must exist in applications

    role

    string

    The role name. Must exist in local_roles

    apply_to_application

    boolean

    Set to true to model environments where the role applies to the top-level application and all its resources.

      "identity_to_permissions": [
        {
          "identity": "0000000001",
          "identity_type": "local_user",
          "role_assignments": [
            {
              "application": "Sample App",
              "role": "user",
              "apply_to_application": true,
              "resources": []
            }
          ]
        },
        {
          "identity": "0000000002",
          "identity_type": "local_user",
          "role_assignments": [
            {
              "application": "Sample App",
              "role": "user",
              "apply_to_application": true,
              "resources": []
            },
            {
              "application": "Sample App",
              "role": "admin",
              "apply_to_application": true,
              "resources": []
            }
          ]
        }
      ]
    

    Enabling Lifecycle Management with SCIM

    Sample Payload

    Simple Custom Application

    This example demonstrates using local users and groups to assign permissions directly to the application and resources.

    Sample Application using Roles

    Custom Properties and Tags

    Set custom properties

    Applications

    Application Properties

    Resources

    Resource Properties

    Resource Connections

    Identities

    Local Users

    local Groups

    Local Roles

    Local Access Credentials

    identity_to_permissions

    Identities to Permissions mapping

    custom property definition
    Custom Application with SCIM (OAA)
    Custom properties
    Veza Tags
    incremental update
    identity_to_permissions
    Automatic Identity Matching
    Automatic Identity Matching
    identity_to_permissions

    custom_properties

    dictionary

    contain property_values validated against the custom_property_definition

    tags

    array

    Specify tags with a key and optional value (optional)

    owners

    array

    See

    local_users

    array

    Contains zero or more local users (see ).

    local_groups

    array

    Contains zero or more (collections of users).

    local_roles

    array

    Defines permissions for any within the application.

    local_access_creds

    array

    Contains any for the application.

    local_agents

    array

    Contains any AI agent entities for the application.

    local_models

    array

    Contains any AI model entities for the application.

    resources

    array

    Contains any and sub-resources.

    okta_app_id

    string

    (Optional, early access) The Okta Application ID for this application. When set, Veza enriches local users with sso_last_login_at timestamps from Okta SSO activity. Requires Veza Support to enable Okta SSO last login enrichment for your tenant. See .

    description

    string

    Shown in Veza entity details, max 255 characters.

    custom_properties

    dictionary

    See .

    sub_resources

    array

    Used for additional resource layers, nested data sources, services, and so on.

    connections

    Optional list of resource connections to external entities discovered by Veza

    tags

    array

    Specify tags with a key and optional value (optional)

    owners

    array

    See

    identities

    identities array

    Correlates the user to a federated identity. Use when your IdP provisions local accounts, or if the local user can be assumed by an external group. Each value must equal one of the attributes Veza compares on the identity provider, such as an Okta login or an Entra ID principal name. See .

    groups

    groups array

    List of any memberships as strings. Must exist in local groups.

    access_creds

    array

    List of local_access_creds IDs associated with this user (optional).

    is_active

    boolean

    If activity state is available from the provider, use this field to make the value available as a searchable property (optional).

    user_type

    string

    Distinguishes between human and service_account user types (optional). Useful for identifying non-human accounts in access reviews.

    principal_id

    string

    The ID for this user in a linked principal template, used for automatic connection. If not supplied, the user id is used (optional).

    created_at

    RFC3339 string

    User creation date (optional), for example 1996-12-19T16:39:57-08:00.

    last_login_at

    RFC3339 string

    (optional)

    password_last_changed_at

    RFC3339 string

    (optional)

    deactivated_at

    RFC3339 string

    (optional)

    access_creds

    array

    List of access credential id values associated with this user (optional). Links the user to their API keys, tokens, or other credentials defined in local_access_creds.

    custom_properties

    dictionary

    See .

    tags

    array

    Specify tags with a key and optional value (optional).

    owners

    array

    See

    groups

    array

    List of local groups this group is a member of (for applications that support adding groups to other groups).

    access_creds

    array

    List of local_access_creds IDs associated with this group (optional).

    created_at

    RFC3339 string

    Group creation date (optional).

    custom_properties

    dictionary

    See .

    tags

    array

    Specify tags with a key and optional value (optional).

    owners

    array

    See .

    roles

    array

    List of sub-role names for nested role hierarchies (optional). An identity assigned to this role inherits all permissions from its sub-roles.

    custom_properties

    dictionary

    See .

    tags

    array

    Specify tags with a key and optional value (optional).

    owners

    array

    See .

    expires_at

    RFC3339 string

    When the credential expires (optional)

    last_used_at

    RFC3339 string

    Last time the credential was used (optional)

    can_expire

    boolean

    Whether the credential can expire

    is_active

    boolean

    Whether the credential is currently active

    custom_properties

    dictionary

    See

    tags

    array

    See

    owners

    array

    See

    resource_types

    array

    Optional list of resource type strings. When specified, separate permission nodes are created per resource type. See below.

    role_assignments

    array

    Any roles assigned to the identity, and the resources they apply to (role/resource must exist in applications).

    permission

    string

    Maps to a permission name from the second section. Must exist in permissions

    resources

    array

    List of resources and sub-resources where the role applies. Must exist in applications

    assignment_properties

    dictionary

    Custom properties on the role assignment itself (optional). Must be defined in role_assignment_properties within custom_property_definition. Useful for tracking assignment-specific metadata such as assignment date or expiration.

    {
      "custom_property_definition": {
        "applications": [
          {
            "application_type": "sample",
            "application_properties": {},
            "local_user_properties": {},
            "local_group_properties": {},
            "local_role_properties": {},
            "resources": []
          }
        ]
      },
      "applications": [
        {
          "name": "Sample App",
          "application_type": "sample",
          "description": "This is a sample app",
          "local_users": [
            {
              "id": "0000000001",
              "name": "bob",
              "identities": [
                "bob@example.com"
              ],
              "is_active": true,
              "created_at": "2022-01-26T20:48:12.460Z"
            },
            {
              "id": "0000000002",
              "name": "jane",
              "identities": [
                "jane@example.com"
              ],
              "groups": [
                "admins"
              ],
              "created_at": "2021-08-13T06:28:13.250Z"
            }
          ],
          "local_groups": [
            {
              "id": "admins",
              "name": "Administrators"
            }
          ],
          "local_roles": [],
          "tags": [],
          "custom_properties": {},
          "resources": [
            {
              "id": "0001",
              "name": "Entity1",
              "resource_type": "thing",
              "description": "Some entity in the application",
              "sub_resources": [
                {
                  "name": "Child 1",
                  "resource_type": "child",
                  "description": "My information about resource"
                }
              ]
            },
            {
              "id": "0002",
              "name": "Entity2",
              "resource_type": "thing",
              "description": "Another entity in the application"
            }
          ]
        }
      ],
      "permissions": [
        {
          "name": "admin",
          "permission_type": [
            "DataRead",
            "DataWrite"
          ],
          "apply_to_sub_resources": false,
          "resource_types": []
        },
        {
          "name": "operator",
          "permission_type": [
            "DataRead",
            "MetadataRead"
          ],
          "apply_to_sub_resources": false,
          "resource_types": []
        },
        {
          "name": "manager",
          "permission_type": [
            "MetadataWrite"
          ],
          "apply_to_sub_resources": false,
          "resource_types": []
        }
      ],
      "identity_to_permissions": [
        {
          "identity": "0000000001",
          "identity_type": "local_user",
          "application_permissions": [
            {
              "application": "Sample App",
              "permission": "operator",
              "apply_to_application": true
            },
            {
              "application": "Sample App",
              "resources": [
                "0001"
              ],
              "permission": "manager"
            }
          ]
        },
        {
          "identity": "admins",
          "identity_type": "local_group",
          "application_permissions": [
            {
              "application": "Sample App",
              "permission": "admin",
              "apply_to_application": true
            }
          ]
        }
      ]
    }
    {
      "applications": [
        {
          "name": "Sample App",
          "application_type": "sample",
          "description": "This is a sample app",
          "local_users": [
            {
              "name": "bob",
              "identities": [
                "bob@example.com"
              ],
              "is_active": true,
              "created_at": "2022-01-26T20:48:12.460Z",
              "id": "0000000001"
            },
            {
              "name": "jane",
              "identities": [
                "jane@example.com"
              ],
              "created_at": "2021-08-13T06:28:13.250Z",
              "id": "0000000002"
            }
          ],
          "local_groups": [],
          "local_roles": [
            {
              "id": "admin",
              "name": "Administrator",
              "permissions": [
                "manage_users"
              ],
              "tags": [],
              "custom_properties": {}
            },
            {
              "id": "user",
              "name": "User",
              "permissions": [
                "view_tickets",
                "close_tickets"
              ],
              "tags": [],
              "custom_properties": {}
            }
          ],
          "tags": [],
          "custom_properties": {},
          "resources": []
        }
      ],
      "permissions": [
        {
          "name": "manage_users",
          "permission_type": [
            "MetadataWrite"
          ],
          "apply_to_sub_resources": false,
          "resource_types": []
        },
        {
          "name": "view_tickets",
          "permission_type": [
            "DataRead"
          ],
          "apply_to_sub_resources": false,
          "resource_types": []
        },
        {
          "name": "close_tickets",
          "permission_type": [
            "MetadataWrite"
          ],
          "apply_to_sub_resources": false,
          "resource_types": []
        }
      ],
      "identity_to_permissions": [
        {
          "identity": "0000000001",
          "identity_type": "local_user",
          "role_assignments": [
            {
              "application": "Sample App",
              "role": "user",
              "apply_to_application": true,
              "resources": []
            }
          ]
        },
        {
          "identity": "0000000002",
          "identity_type": "local_user",
          "role_assignments": [
            {
              "application": "Sample App",
              "role": "user",
              "apply_to_application": true,
              "resources": []
            },
            {
              "application": "Sample App",
              "role": "admin",
              "apply_to_application": true,
              "resources": []
            }
          ]
        }
      ]
    }
    Custom Properties
    Entity Owners
    local_identities
    local groups
    roles
    access credentials
    resources
    Okta SSO last login enrichment
    Custom Properties
    Resource Connections
    Entity Owners
    Automatic Identity Matching
    group
    Custom Properties
    tags
    Entity Owners
    Custom Properties
    Entity Owners
    Custom Properties
    Entity Owners
    Custom Properties
    Veza Tags
    Entity Owners

    Application

    Classes for constructing an OAA JSON payload for Custom Application

    Copyright 2026 Veza Technologies Inc.

    Use of this source code is governed by the MIT license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

    Global Variables


    • PROPERTY_NAME_REGEX


    class OAAPermission

    Canonical permissions used by Veza Authorization Framework.

    Used to describe the raw data or metadata permissions granted by CustomPermission


    class OAAIdentityType

    Types of identities for permission mapping.


    Base class for CustomApplication.


    Class for modeling application authorization using the OAA Application template.

    CustomApplication class consists of identities, resources and permissions and produces the OAA JSON payload for the custom application template.

    Class uses dictionaries to track most entities that can be referenced after creation. Dictionaries keys are case insensitive of the entity identifier (name or id). This applies to local_users, local_groups, local_roles, idp_identities, resources and custom_permissions.

    Args:

    • name (str): Name of custom application

    • application_type (str): Searchable property, can be unique or shared across multiple applications

    • description (str, optional): Description for application. Defaults to None.

    Attributes:

    • application_type (str): Searchable application type

    • custom_permissions (dict[OAAPermission]): Dictionary of class instances

    • description (str): Description for application


    Legacy method for backwards compatibility.

    Deprecated: Access should be added through identity (local_role, local_group, idp)


    Create an Access Credential

    Access creds can be used to represent alternative access methods such as API keys or application integrations.

    Access creds can be assigned roles and permissions similar to local users. Access credentials can exist independently for use cases such as administratively created integrations or can be assigned to a local user for use cases like personal access tokens.

    Args:

    • unique_id (str): unique identifier for access cred

    • name (str): name for access cred

    Raises:

    • OAATemplateException: Access credential with unique ID already exists

    Returns:

    • AccessCred: New access cred


    Create a new local agent for the application.

    Agents represent AI agent entities. They can be assigned to groups, have access credentials, reference models, and be authorized via permissions or roles similar to local users.

    Args:

    • name (str): Display name for agent

    • unique_id (str, optional): Unique identifier for agent for reference by ID

    • ai_platform (str, optional): AI platform the agent runs on. Defaults to "".

    Raises:

    • OAATemplateException: Agent with identifier already exists

    Returns: LocalAgent


    Create a new custom permission.

    Creates a new CustomPermission object for the application that can be used to authorize identities to the application, resources/sub-resource or as part of a role.

    Args:

    • name (str): Name of the permission

    • permissions (list[OAAPermission]): Canonical permissions the custom permission represents

    • apply_to_sub_resources (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to False.

    Returns: CustomPermission


    Create an IdP principal identity.

    IdP users and groups can be authorized directly to applications and resources by associating custom application permissions and roles with an IdP identity's name or email.

    Args:

    • name (str): IdP unique identifier for user or group.

    Returns: IdPIdentity


    Create a new local group.

    Groups can be associated to resources via permissions or roles. All users in the local group are granted the group's authorization.

    Local groups will be identified by name by default, if unique_id is provided it will be used as the identifier instead

    Local groups can be referenced after creation using .local_groups dictionary attribute. Dictionary is case insensitive keyed by unique_id or name if not using unique_id.

    Args:

    • name (str): Display name for group

    • identities (list): List of IdP identities to associate group with.

    • unique_id (str, optional): Unique identifier for group for reference by ID

    Returns: LocalGroup


    Create a new local role.

    • A local role represents a collection of permissions.

    • Identities (local user, group, idp user) can be assigned a role to the application or resource, granting the role's permissions.

    • Local roles will be identified by name by default, if unique_id is provided it will be used as the identifier instead.

    • Local roles can be referenced after creation if needed through

    Args:

    • name (str): Display name for role

    • permissions (list): List of Custom Permission names to include in role. CustomPermission must be created separately.

    • unique_id (str, optional): Unique identifier for role for reference by ID

    Returns: LocalRole


    Create a new local user for application.

    Local users can be assigned to groups and associated with resources via permissions or roles. Groups and identities can be provided at creation or added later. See Identity and LocalUser class for operations.

    Local users will be identified by name by default, if unique_id is provided it will be used as the identifier instead.

    Local users can be referenced after creation using the .local_users dictionary attribute. Dictionary is case insensitivekeyed by unique_id or name if not using unique_id.

    Use unique_id when name is not guaranteed to be unique. All permission, group and role assignments will be referenced by unique_id.

    Args:

    • name (str): Display name for user

    • identities (list): List of identities as strings (usually email) for local user. Used to map local user to discovered IdP identities.

    • groups (list[LocalGroup]): List of group names (as string) to add user to

    Returns: LocalUser


    Create a new local model for the application.

    Models represent AI model entities. They can be referenced by agents.

    Args:

    • name (str): Display name for model

    • unique_id (str, optional): Unique identifier for model for reference by ID

    • ai_platform (str, optional): AI platform the model runs on. Defaults to "".

    Raises:

    • OAATemplateException: Model with identifier already exists

    Returns: LocalModel


    Add Entity Owner

    Add an entity owner to the application.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Create a new resource under the application.

    Resource type is used to group and filter application resources. It should be consistent for all common resources of an application.

    Returns new resource object.

    Resource is identified by name by default unless unique_id is provided. name must be unique if not using unique_id.

    Resources can be referenced after creation using the .resources dictionary attribute. Dictionary is keyed by unique_id or name if not using unique_id. Use unique_id when name is not guaranteed to be unique.

    Args:

    • name (str): Name of resources

    • resource_type (str): Type for resource

    • description (str, optional): Description of resources. Defaults to None.

    Returns: CustomResource


    Add a tag to the Application

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Return the 'applications' section of the payload as serializable dictionary.


    Add a custom permission to the application.

    Deprecated: See CustomApplication.add_custom_permission()

    Args:

    • custom_permission (CustomPermission): CustomPermission class

    Raises:

    • Exception: Duplicate Keys

    Returns:

    • CustomPermission: The defined custom Permission


    Collect authorizations for all identities into a single list.


    Get the OAA payload.

    Returns the complete OAA template payload for application as serializable dictionary

    Returns:

    • dict: OAA payload as dictionary


    Return the 'permissions' section of the payload as serializable dictionary.


    Set a custom property value for the application.

    Property name must be defined for CustomApplication before calling set_property. See example below and ApplicationPropertyDefinitions.define_application_property for more information on defining properties.

    Args:

    • property_name (str): Name of property to set value for, property names must be defined as part of the application property_definitions

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property name is not defined

    Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_application_property(name="my_property", property_type=OAAPropertyType.STRING) >>> app.set_property("my_property", "property value")


    Class for resources and sub-resources.

    Should be used for representing components of the application to which authorization is granted. Each resource has a name and a type. The type can be used for grouping and filtering.

    Arguments:

    • name (str): display name for resource, must be unique to parent application or resource unless using unique_id

    • resource_type (str): type for resource

    • description (str): description for resource

    Attributes:

    • name (str): display name for resource, must be unique to parent application or resource

    • unique_id (str): resource's unique identifier if provided.

    • resource_type (str): type for resource


    No longer supported, access should be added through identity (local_user, local_group, idp)


    Add Entity Owner

    Add an entity owner to the resource.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add an external connection to the resource.

    Used to add a relationship to another entity discovered by Veza such as a service account or AWS IAM role.

    Args:

    • id (str): Unique identifier for connection entity

    • node_type (str): Veza type for connecting node


    Create a new sub-resource under current resource

    Args:

    • name (str): display name for resource

    • resource_type (str): type for resource

    • description (str, optional): String description. Defaults to None.

    Returns: CustomResource


    Add a new tag to resource.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set the value for a custom property on a resource or sub-resource.

    Property name must be defined for resource type before calling set_property(). See example below and ApplicationPropertyDefinitions.define_resource_property for more information on defining properties.

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property_name is not defined

    Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_resource_property(resource_type="cog", name="my_property", property_type=OAAPropertyType.STRING) >>> cog1 = app.add_resource(name="cog1", resource_type="cog") >>> cog1.set_property("my_property", "this value")


    Return the dictionary representation of resource.


    Base class for deriving all identity types (should not be used directly).

    Args:

    • name (str): name of identity

    • identity_type (OAAIdentityType): Veza Identity Type (local_user, local_group, idp)

    • unique_id (str, optional): ID of entity for reference by ID

    Attributes:

    • name (str): name of identity

    • identity_type (OAAIdentityType): Veza Identity Type (local_user, local_group, idp)

    • application_permissions (list[CustomPermission]): List of permissions identity has directly to custom application


    Add Entity Owner

    Add an entity owner for user or group.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a permission to an identity.

    Permission can apply to either the application or application resource/sub-resources

    Args:

    • permissions ([str]): List of strings representing the permission names

    • resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

    • apply_to_application (bool): Apply permission to application when True, defaults to False


    Add a role to an identity.

    Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

    Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

    Args:

    • role (str): Name of role as string

    • resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

    • apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any


    Add a new tag to identity.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Get a JSON serializable dictionary of all the identity's permissions and roles.

    Formats the identity's permissions and roles for the Custom Application template payload

    Returns:

    • dict: JSON serializable dictionary of all the identity's permissions and roles


    Set a custom defined property to a specific value on an identity.

    Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example:

    app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")


    Types of local user account, human or service account.


    LocalUser identity, derived from Identity base class.

    Used to model an application user. Can be associated with an external IdP user, or represent a local account.

    Args:

    • name (str): name of identity

    • identities (list): list of strings for IdP identity association

    • groups (list[LocalGroup]): list of group names as strings to add user too

    Attributes:

    • name (str): name of identity

    • id (str): ID of entity for ID based reference

    • email (string): Users email address


    Add access cred to user (access cred must be created separately)

    Args:

    • access_cred (str): unique identifier of access cred


    Add user to local group (group must be created separately).

    Args:

    • group (str): identifier of local group


    Add multiple identities to a local user from a list.

    Args:

    • identities (list[str]): list of identities to add to user


    Add an identity to user.

    Identity should match the email address or another principal identifier for an IdP user (Okta, Azure, etc.). Veza will create a connection from the application local user to IdP identity.

    Args:

    • identity (str): email or identifier for IdP user


    Add Entity Owner

    Add an entity owner for user or group.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a permission to an identity.

    Permission can apply to either the application or application resource/sub-resources

    Args:

    • permissions ([str]): List of strings representing the permission names

    • resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

    • apply_to_application (bool): Apply permission to application when True, defaults to False


    Add a role to an identity.

    Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

    Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

    Args:

    • role (str): Name of role as string

    • resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

    • apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any


    Add a new tag to identity.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Get a JSON serializable dictionary of all the identity's permissions and roles.

    Formats the identity's permissions and roles for the Custom Application template payload

    Returns:

    • dict: JSON serializable dictionary of all the identity's permissions and roles


    Set a custom defined property to a specific value on an identity.

    Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example:

    app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")


    Output user to dictionary for payload.


    LocalGroup identity.

    Derived from Identity base class. Used to represent groups of local users for application.

    Args:

    • name (str): name of group

    • identities (list): list of strings for IdP identity association

    • unique_id (string, optional): Unique identifier for group

    Attributes:

    • name (str): name of identity

    • identities (list): list of strings for IdP identity association

    • groups (list[LocalGroup]): list of group names as strings that group is member of for nested groups


    Add a nested group to local group (group must be created separately).

    Args:

    • group (str): identifier of local group


    Add an identity to group.

    The email address or another valid identifier should match that of an IdP principal (Okta, Azure, etc.). Veza will create a connection from the application local group to IdP identity.

    Args:

    • identity (str): primary IdP identifier for group to associate


    Add Entity Owner

    Add an entity owner for user or group.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a permission to an identity.

    Permission can apply to either the application or application resource/sub-resources

    Args:

    • permissions ([str]): List of strings representing the permission names

    • resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

    • apply_to_application (bool): Apply permission to application when True, defaults to False


    Add a role to an identity.

    Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

    Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

    Args:

    • role (str): Name of role as string

    • resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

    • apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any


    Add a new tag to identity.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Get a JSON serializable dictionary of all the identity's permissions and roles.

    Formats the identity's permissions and roles for the Custom Application template payload

    Returns:

    • dict: JSON serializable dictionary of all the identity's permissions and roles


    Set a custom defined property to a specific value on an identity.

    Property name must be defined for identity type before calling set_property(). See example below for LocalUser and ApplicationPropertyDefinitions.define_local_user_property for more information on defining properties. Property must be defined for the correct Identity type (LocalUser or LocalGroup, IdPIdentity does not support custom properties).

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example:

    app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_user_property(name="my_property", property_type=OAAPropertyType.STRING) >>> user1 = app.add_local_user(name="user1") >>> user1.set_property("my_property", "value for user1")


    Output group to dictionary for payload.


    IdP identity derived from Identity base class.

    Used to associate IdP identities (users or groups) directly to resource where concept of local users/groups doesn't apply to application.

    Args:

    • name (str): Primary IdP identifier for identity (email, group name, etc)

    • property_definitions (ApplicationPropertyDefinitions, optional): Property definitions for role assignment validation

    Attributes:

    • name (str): name of identity

    • identity_type (OAAIdentityType): Veza Identity Type, (idp)

    • application_permissions (list[CustomPermission]): permissions identity has directly to custom application


    Add Entity Owner

    Add an entity owner for user or group.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a permission to an identity.

    Permission can apply to either the application or application resource/sub-resources

    Args:

    • permissions ([str]): List of strings representing the permission names

    • resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

    • apply_to_application (bool): Apply permission to application when True, defaults to False


    Add a role to an identity.

    Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

    Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

    Args:

    • role (str): Name of role as string

    • resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

    • apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any


    Add a new tag to identity.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Get a JSON serializable dictionary of all the identity's permissions and roles.

    Formats the identity's permissions and roles for the Custom Application template payload

    Returns:

    • dict: JSON serializable dictionary of all the identity's permissions and roles


    Set custom IdP property (no functionality).

    IdP identities do not support custom properties since the identity is discovered through the provider (Okta, Azure, etc)


    Access Credential derived from Identity base class.

    Access Creds can be used to represent non-user based methods that grant access such as API keys or integrations.

    AccessCreds can be assigned roles or permissions to an application or resource. An AccessCred can stand-alone or be associated to a local user.

    Args:

    • unique_id (str): Unique identifier for access cred

    • name (str): Name for access cred, does not need to be unique

    Attributes:

    • unique_id (str): Unique identifier for access cred

    • name (str): Name for access cred, does not need to be unique

    • is_active (bool): Indicate if credential is active, defaults to True


    Add Entity Owner

    Add an entity owner to the access credential.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a permission to an identity.

    Permission can apply to either the application or application resource/sub-resources

    Args:

    • permissions ([str]): List of strings representing the permission names

    • resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

    • apply_to_application (bool): Apply permission to application when True, defaults to False


    Add a role to an identity.

    Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

    Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

    Args:

    • role (str): Name of role as string

    • resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

    • apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any


    Add a new tag to identity.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Get a JSON serializable dictionary of all the identity's permissions and roles.

    Formats the identity's permissions and roles for the Custom Application template payload

    Returns:

    • dict: JSON serializable dictionary of all the identity's permissions and roles


    Set a custom defined property to a specific value on an access credential.

    Property name must be defined for access credentials before calling set_property(). See example below and ApplicationPropertyDefinitions.define_access_cred_property for more information on defining properties.

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.

    Example:

    app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_access_cred_property(name="my_property", property_type=OAAPropertyType.STRING) >>> cred1 = app.add_access_cred(unique_id="cred001", name="Cred 001") >>> cred1.set_property("my_property", "value for cred001")


    Output Access credential dictionary for payload


    Local Agent identity, derived from Identity base class.

    Represents an AI agent entity within an application. Agents can be assigned to groups, have access credentials, reference models, and be authorized via permissions or roles.

    Args:

    • name (str): Display name for agent

    • unique_id (str, optional): Unique identifier for agent for reference by ID

    • ai_platform (str, optional): AI platform the agent runs on

    Attributes:

    • name (str): Display name

    • unique_id (str): Unique identifier if provided

    • ai_platform (str): AI platform

    • ai_agent_publisher


    Add access cred to agent (access cred must be created separately).

    Args:

    • access_cred (str): unique identifier of access cred


    Add agent to local group (group must be created separately).

    Args:

    • group (str): identifier of local group


    Add a model reference to agent (model must be created separately).

    Args:

    • model (str): identifier of local model


    Add Entity Owner

    Add an entity owner for user or group.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a permission to an identity.

    Permission can apply to either the application or application resource/sub-resources

    Args:

    • permissions ([str]): List of strings representing the permission names

    • resource (CustomResource, optional): Custom resource, if None permission is applied to application. Defaults to None.

    • apply_to_application (bool): Apply permission to application when True, defaults to False


    Add a role to an identity.

    Role to authorize identity to either the application or application resource/sub-resource based on role's permissions.

    Role assignment properties can be set with the assignment_properties dictionary parameter with property names as the keys. Role assignment properties types must be defined on the application prior to setting.

    Args:

    • role (str): Name of role as string

    • resources (List[CustomResource], optional): Custom resource, if None role is applied to application. Defaults to None.

    • apply_to_application (bool, optional): Apply permission to application when True, False will replace existing value, None will leave previous setting if any


    Add a new tag to identity.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Get a JSON serializable dictionary of all the identity's permissions and roles.

    Formats the identity's permissions and roles for the Custom Application template payload

    Returns:

    • dict: JSON serializable dictionary of all the identity's permissions and roles


    Set a custom defined property on an agent.

    Property name must be defined for agents before calling set_property().

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Output agent to dictionary for payload.


    Represents an AI model entity within an application.

    Models can be referenced by agents and have custom properties, tags, and owners.

    Args:

    • name (str): Display name for model

    • unique_id (str, optional): Unique identifier for model for reference by ID

    • ai_platform (str, optional): AI platform the model runs on

    Attributes:

    • name (str): Display name

    • unique_id (str): Unique identifier if provided

    • ai_platform (str): AI platform

    • ai_model_publisher


    Add Entity Owner

    Add an entity owner to the model.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a new tag to model.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Defaults to "".


    Set a custom defined property on a model.

    Property name must be defined for models before calling set_property().

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property with property_name is not defined.


    Output model to dictionary for payload.


    Represent a Custom Application Local Role.

    Local Roles are a collection of permissions (as CustomPermission). Roles can be used to associate a local user, group or IdP identity to an application, resource or sub-resource.

    Permissions can either be assigned at creation and/or added later.

    If the CustomPermission definition includes resource types in the resource_types list, the permission will only be assigned to resources/sub-resources that match that type as part of an assignment.

    Args:

    • name (str): name of local role

    • permissions (list[CustomPermission], optional): List of custom permission names (strings) to associate with the role. Defaults to empty list.

    • unique_id (string, optional): Unique identifier for role for identification by ID

    Attributes:

    • name (str): name of local role

    • unique_id (str): Unique identifier for role for identification by ID

    • permissions (list[CustomPermission]): list of custom permission names (strings) to associate with the role


    Add Entity Owner

    Add an entity owner to the local role.

    Args:

    • external_id (str): IDP identity of the owner

    • owner_type (str): IDP Node type of the entity, OAAOwnerType enum. For Custom IDP owner_type should be OAA.<IDPType>.IDPUser

    • is_primary (bool, optional): Is Primary Owner. Defaults to False.


    Add a permission to the role.

    Args:

    • permissions (list): List of permission names (strings) to add to role


    Add a nested sub-role to the role (nested role must be created separately)

    Args:

    • role (str): identifier of the local role to nest inside this role


    Add a new tag to role.

    Args:

    • key (str): Key for tag, aka name. Must be present and must be letters, numbers or _ (underscore) only.

    • value (str, optional): Value for Tag, will appear in Veza as key:value. Must be letters, numbers, whitespace and the special characters @,._- only. Defaults to "".


    Set the value for custom property on a local role.

    Property name must be defined for local roles before calling set_property(). See example below and ApplicationPropertyDefinitions.define_local_role_property for more information on defining properties.

    Args:

    • property_name (str): Name of property to set value for

    • property_value (Any): Value for property, type should match OAAPropertyType for property definition

    • ignore_none (bool, optional): Do not set property if value is None. Defaults to False.

    Raises:

    • OAATemplateException: If property name is not defined.

    Example: app = CustomApplication("App", application_type="example") >>> app.property_definitions.define_local_role_property(name="my_property", property_type=OAAPropertyType.STRING) >>> role1 = app.add_local_role(name="role1") >>> role1.set_property(property_name="my_property", property_value="role1s value")


    Convert role to dictionary for inclusion in JSON payload.

    Returns:

    • dict: serializable dictionary of role


    CustomPermission class for defining CustomApplication permissions.

    • Custom permissions represent the named permissions for the application in its terms (e.g. "Admin" or "PUSH") and define the Veza canonical mapping (e.g. DataRead, MetadataRead, DataWrite).

    • A permission can either be applied directly to an application or resource or assigned as part of a role.

    • Optionally, when permissions are used as part of a role, if the resource_types list is populated the permission will only be applied to resources who's type is in the resource_types list when the role is applied to a resource.

    Args:

    • name (str): Display name for permission

    • permissions (list): List of OAAPermission enums that represent the canonical permissions

    • apply_to_sub_resources (bool, optional): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource. Defaults to False.

    Attributes:

    • name (str): Display name for permission

    • permissions (list[OAAPermission]): List of OAAPermission enums that represent the canonical permissions

    • apply_to_sub_resources (bool): If true, when permission is applied to the application or resource, identity also has permission to all children of application/resource.


    Add a resource type to the resource_types list.

    Extends the list of resource types permission applies to when used in role assignment.

    Args:

    • resource_type (str): The resource type string value


    Returns dictionary representation for payload.


    Model for defining custom properties for application and its entities (users, groups, roles, resources).

    Property definitions define the names for additional entity properties and the expected type.

    Args:

    • application_type (str): type of custom application property definitions apply to

    Attributes:

    • application_properties (dict): property definitions for application

    • local_user_properties (dict): property definitions for local users

    • local_group_properties (dict): property definitions for local groups


    Define an access cred property.

    Args:

    • name (str): name for property

    • property_type (OAAPropertyType): type for property


    Define an application property.

    Args:

    • name (str): name for property

    • property_type (OAAPropertyType): type for property


    Define a local agent property.

    Args:

    • name (str): name for property

    • property_type (OAAPropertyType): type for property


    Define a local group property.

    Args:

    • name (str): name for property

    • property_type (OAAPropertyType): type for property


    Define a local model property.

    Args:

    • name (str): name for property

    • property_type (OAAPropertyType): type for property


    Define a local role property.

    Args:

    • name (str): name for property

    • property_type (OAAPropertyType): type for property


    Define a local user property.

    Args:

    • name (str): name for property

    • property_type (OAAPropertyType): type for property


    Define a property for a resource by type of resource.

    Args:

    • resource_type (str): type of resource property definition is for

    • name (str): property name

    • property_type (OAAPropertyType): type for property



    Return property definitions as dictionary ready for OAA payload


    Check property name for valid characters

    Raises an exception if the name string does not match required pattern. Name must start with a character and can only contain letters and _ character.

    Args:

    • name (str): name of property to validate

    Raises:

    • OAATemplateException: Name is not a string

    • OAATemplateException: Name contains invalid characters or does not start with a letter


    Validate that a property name has been defined for given resource type.

    Args:

    • property_name (str): name of property to validate

    • entity_type (str): type of entity custom property is for (application, local_user, local_group, local_role, resource)

    • resource_type (str): (optional) type for validating resource property names, only applicable to entity_type resource

    Raises:

    • OAATemplateException: If property name has not been previously defined for entity

    identity_to_permissions (dict): Mapping of authorizations for identities to resources
  • idp_identities (dict[IdPIdentity]): Contains federated identities without a corresponding local account

  • local_groups (dict[LocalGroup]): Contains application groups (collections of users)

  • local_roles (dict[LocalRole]): Contains application roles (collections of permissions)

  • local_users (dict[LocalUser]): Contains users local to the application and their properties

  • name (str): Name of custom application

  • properties (dict): key value pairs of property values, property keys must be defined as part of the property_definitions

  • property_definitions (ApplicationPropertyDefinitions): Custom property names and types for the application

  • resources (dict[CustomResource]): Contains data resources and subresources within the application

  • ai_agent_publisher (str, optional): Publisher of the AI agent. Defaults to "".

    resource_types (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list.

    .local_roles
    case insensitive dictionary attribute.
  • When a permission that has resource_types is added to a role, it will only apply to resources with a matching resource_type

  • unique_id (str, optional): Unique identifier for user for reference by ID
    ai_model_publisher (str, optional): Publisher of the AI model. Defaults to "".
  • ai_model_family (str, optional): Model family. Defaults to "".

  • ai_model_series (str, optional): Model series. Defaults to "".

  • unique_id
    (str, optional): Unique identifier for resource. defaults to None.
    application_name (str): name of parent application
  • resource_key (str, optional): for sub-resources the full unique identifier required for identity_to_permissions section. Defaults to name or unique_id if not provided.

  • property_definitions (ApplicationPropertyDefinitions, optional): Property definitions structure for the resource

  • unique_id (str, optional): Optional unique identifier for the resource. Defaults to None.

  • application_name (str): name of parent application
  • resource_key (str): for sub-resources represents the sub-resource's parent path

  • sub_resources (dict): dictionary of sub-resources keyed by name

  • properties (dict): dictionary of properties set for resource

  • tags (list[Tag]): list of tags

  • unique_id
    (str, optional): Unique identifier for new subresource, Defaults to
    name
    .
    resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys
  • application_roles (LocalRole): List of roles identity has directly to custom application

  • resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

  • properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

  • tags (list[Tag]): List of tags

  • assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

    unique_id (string, optional): For reference by ID
    identities
    (list): list of strings for IdP identity association
  • groups (list[LocalGroup]): list of group names as strings to add user too

  • identity_type (OAAIdentityType): Veza Identity Type (local_user)

  • application_permissions (list[CustomPermission]): Permissions identity has directly to custom application

  • resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys

  • application_roles (list[LocalRole]): Custom application roles assigned directly to the identity

  • resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

  • properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

  • tags (list[Tag]): List of tags

  • is_active (bool): Defaults to None for unset

  • created_at (str): RFC3339 time stamp for user creation

  • last_login_at (str): RFC3339 time stamp for last login

  • deactivated_at (str): RFC3339 for user deactivate time

  • password_last_changed_at (str): RFC3339 time stamp for last password change

  • user_type (LocalUserType): Set the local user account type

  • assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

    identity_type (OAAIdentityType): Veza Identity Type, local_group
  • application_permissions (list[CustomPermission]): permissions identity has directly to custom application

  • resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys

  • application_roles (list[LocalRole]): list of roles identity has directly to custom application

  • resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

  • properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

  • tags (list[Tag]): List of tags

  • created_at (str): RFC3339 time stamp for group creation time

  • assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

    resource_permissions (dict): Dictionary of custom permissions associated with resources and sub-resources. Key is permission, value is list of resource keys
  • application_roles (list[LocalRole]): roles identity has directly to custom application

  • resource_roles (dict): Dictionary of local_roles for resources and sub-resources. Key is roles, value is list of resource keys

  • properties (dict): Dictionary of properties for identity, allowed values will vary by identity type

  • tags (list[Tag]): List of tags

  • assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

    created_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty
  • expires_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty

  • last_used_at (str): Time access cred was created at as RFC3339 timestampe, defaults to empty

  • can_expire (bool): Boolean to indicate if credential type can exipre, defaults to unset

  • assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

    ai_agent_publisher (str, optional): Publisher of the AI agent
  • property_definitions (ApplicationPropertyDefinitions, optional): Property definitions for the application

  • (str): AI agent publisher
  • is_active (bool): Whether agent is active, defaults to None for unset

  • created_at (str): RFC3339 timestamp for agent creation

  • groups (list): List of group names the agent belongs to

  • access_creds (list): List of access credential IDs associated with the agent

  • models (list): List of model names/IDs the agent uses

  • tags (list[Tag]): List of tags

  • owners (list[EntityOwner]): List of entity owners

  • properties (dict): Custom properties

  • assignment_properties (dict, optional): Custom properties for the role assignment. Defaults to no properties.

    ai_model_publisher (str, optional): Publisher of the AI model
  • ai_model_family (str, optional): Model family

  • ai_model_series (str, optional): Model series

  • property_definitions (ApplicationPropertyDefinitions, optional): Property definitions for the application

  • (str): AI model publisher
  • ai_model_family (str): AI model family

  • ai_model_series (str): AI model series

  • created_at (str): RFC3339 timestamp for model creation

  • tags (list[Tag]): List of tags

  • owners (list[EntityOwner]): List of entity owners

  • properties (dict): Custom properties

  • roles (list[LocalRole]): list of roles nested inside the role
  • tags (list[Tag]): list of Tags instances

  • resource_types (list, optional): List of resource types as strings that the permission relates to. Defaults to empty list.

    resource_types (list): List of resource types as strings that the permission relates to.

    local_role_properties (dict): property definitions for local roles
  • resources (dict): property definitions for resources keyed by resource type

  • class Application

    method __init__

    class CustomApplication

    method __init__

    method add_access

    method add_access_cred

    method add_agent

    method add_custom_permission

    method add_idp_identity

    method add_local_group

    method add_local_role

    method add_local_user

    method add_model

    method add_owner

    method add_resource

    method add_tag

    method app_dict

    method define_custom_permission

    method get_identity_to_permissions

    method get_payload

    method permissions_dict

    method set_property

    class CustomResource

    method __init__

    method add_access

    method add_owner

    method add_resource_connection

    method add_sub_resource

    method add_tag

    method set_property

    method to_dict

    class Identity

    method __init__

    method add_owner

    method add_permission

    method add_role

    method add_tag

    method get_identity_to_permissions

    method set_property

    class LocalUserType

    class LocalUser

    method __init__

    method add_access_cred

    method add_group

    method add_identities

    method add_identity

    method add_owner

    method add_permission

    method add_role

    method add_tag

    method get_identity_to_permissions

    method set_property

    method to_dict

    class LocalGroup

    method __init__

    method add_group

    method add_identity

    method add_owner

    method add_permission

    method add_role

    method add_tag

    method get_identity_to_permissions

    method set_property

    method to_dict

    class IdPIdentity

    method __init__

    method add_owner

    method add_permission

    method add_role

    method add_tag

    method get_identity_to_permissions

    method set_property

    class AccessCred

    method __init__

    method add_owner

    method add_permission

    method add_role

    method add_tag

    method get_identity_to_permissions

    method set_property

    method to_dict

    class LocalAgent

    method __init__

    method add_access_cred

    method add_group

    method add_model

    method add_owner

    method add_permission

    method add_role

    method add_tag

    method get_identity_to_permissions

    method set_property

    method to_dict

    class LocalModel

    method __init__

    method add_owner

    method add_tag

    method set_property

    method to_dict

    class LocalRole

    method __init__

    method add_owner

    method add_permissions

    method add_role

    method add_tag

    method set_property

    method to_dict

    class CustomPermission

    method __init__

    method add_resource_type

    method to_dict

    class ApplicationPropertyDefinitions

    method __init__

    method define_access_cred_property

    method define_application_property

    method define_local_agent_property

    method define_local_group_property

    method define_local_model_property

    method define_local_role_property

    method define_local_user_property

    method define_resource_property

    method define_role_assignment_property

    method to_dict

    method validate_name

    method validate_property_name

    __init__(name, application_type, description=None)
    __init__(name: 'str', application_type: 'str', description: 'str' = None) → None
    add_access(identity, identity_type, permission, resource=None)
    add_access_cred(unique_id: 'str', name: 'str') → AccessCred
    add_agent(
        name: 'str',
        unique_id: 'str' = None,
        ai_platform: 'str' = '',
        ai_agent_publisher: 'str' = ''
    ) → LocalAgent
    add_custom_permission(
        name: 'str',
        permissions: 'List[OAAPermission]',
        apply_to_sub_resources: 'bool' = False,
        resource_types: 'List[str]' = None
    ) → CustomPermission
    add_idp_identity(name: 'str') → IdPIdentity
    add_local_group(
        name: 'str',
        identities: 'List[str]' = None,
        unique_id: 'str' = None
    ) → LocalGroup
    add_local_role(
        name: 'str',
        permissions: 'List[str]' = None,
        unique_id: 'str' = None
    ) → LocalRole
    add_local_user(
        name: 'str',
        identities: 'List[str]' = None,
        groups: 'List[str]' = None,
        unique_id: 'str' = None
    ) → LocalUser
    add_model(
        name: 'str',
        unique_id: 'str' = None,
        ai_platform: 'str' = '',
        ai_model_publisher: 'str' = '',
        ai_model_family: 'str' = '',
        ai_model_series: 'str' = ''
    ) → LocalModel
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_resource(
        name: 'str',
        resource_type: 'str',
        description: 'str' = None,
        unique_id: 'str' = None
    ) → CustomResource
    add_tag(key: 'str', value: 'str' = '') → None
    app_dict() → dict
    define_custom_permission(
        custom_permission: 'CustomPermission'
    ) → CustomPermission
    get_identity_to_permissions() → list
    get_payload() → dict
    permissions_dict() → dict
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    __init__(
        name: 'str',
        resource_type: 'str',
        description: 'str',
        application_name: 'str',
        resource_key: 'str' = None,
        property_definitions: 'ApplicationPropertyDefinitions' = None,
        unique_id: 'str' = None
    ) → None
    add_access(identity, identity_type, permission)
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_resource_connection(id: 'str', node_type: 'str') → None
    add_sub_resource(
        name: 'str',
        resource_type: 'str',
        description: 'str' = None,
        unique_id: 'str' = None
    ) → CustomResource
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        identity_type: 'OAAIdentityType',
        unique_id: 'str' = None,
        property_definitions: 'ApplicationPropertyDefinitions' = None
    ) → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_permission(
        permission: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'bool' = False
    ) → None
    add_role(
        role: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'Optional[bool]' = None,
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    get_identity_to_permissions(application_name: 'str') → dict
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    __init__(
        name: 'str',
        identities: 'List[str]' = None,
        groups: 'List[str]' = None,
        unique_id: 'str' = None,
        property_definitions: 'ApplicationPropertyDefinitions' = None
    ) → None
    add_access_cred(access_cred: 'str') → None
    add_group(group: 'str') → None
    add_identities(identities: 'List[str]') → None
    add_identity(identity: 'str') → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_permission(
        permission: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'bool' = False
    ) → None
    add_role(
        role: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'Optional[bool]' = None,
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    get_identity_to_permissions(application_name: 'str') → dict
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name,
        identities=None,
        unique_id: 'str' = None,
        property_definitions: 'ApplicationPropertyDefinitions' = None
    )
    add_group(group: 'str') → None
    add_identity(identity: 'str') → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_permission(
        permission: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'bool' = False
    ) → None
    add_role(
        role: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'Optional[bool]' = None,
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    get_identity_to_permissions(application_name: 'str') → dict
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        property_definitions: 'ApplicationPropertyDefinitions' = None
    ) → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_permission(
        permission: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'bool' = False
    ) → None
    add_role(
        role: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'Optional[bool]' = None,
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    get_identity_to_permissions(application_name: 'str') → dict
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    __init__(
        unique_id: 'str',
        name: 'str',
        property_definitions: 'ApplicationPropertyDefinitions' = None
    ) → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_permission(
        permission: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'bool' = False
    ) → None
    add_role(
        role: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'Optional[bool]' = None,
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    get_identity_to_permissions(application_name: 'str') → dict
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str' = None,
        ai_platform: 'str' = '',
        ai_agent_publisher: 'str' = '',
        property_definitions: 'ApplicationPropertyDefinitions' = None
    ) → None
    add_access_cred(access_cred: 'str') → None
    add_group(group: 'str') → None
    add_model(model: 'str') → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_permission(
        permission: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'bool' = False
    ) → None
    add_role(
        role: 'str',
        resources: 'List[CustomResource]' = None,
        apply_to_application: 'Optional[bool]' = None,
        assignment_properties: 'Optional[dict]' = None
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    get_identity_to_permissions(application_name: 'str') → dict
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        unique_id: 'str' = None,
        ai_platform: 'str' = '',
        ai_model_publisher: 'str' = '',
        ai_model_family: 'str' = '',
        ai_model_series: 'str' = '',
        property_definitions: 'ApplicationPropertyDefinitions' = None
    ) → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        permissions: 'List[str]' = None,
        unique_id: 'str' = None,
        property_definitions: 'ApplicationPropertyDefinitions' = None
    ) → None
    add_owner(
        external_id: 'str',
        owner_type: 'str',
        is_primary: 'bool' = False
    ) → None
    add_permissions(permissions: 'List[str]') → None
    add_role(role: 'str') → None
    add_tag(key: 'str', value: 'str' = '') → None
    set_property(
        property_name: 'str',
        property_value: 'any',
        ignore_none: 'bool' = False
    ) → None
    to_dict() → dict
    __init__(
        name: 'str',
        permissions: 'List[OAAPermission]',
        apply_to_sub_resources: 'bool' = False,
        resource_types: 'list' = None
    ) → None
    add_resource_type(resource_type: 'str') → None
    to_dict() → dict
    __init__(application_type: 'str') → None
    define_access_cred_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_application_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_local_agent_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_local_group_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_local_model_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_local_role_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_local_user_property(name: 'str', property_type: 'OAAPropertyType') → None
    define_resource_property(
        resource_type: 'str',
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    define_role_assignment_property(
        name: 'str',
        property_type: 'OAAPropertyType'
    ) → None
    to_dict() → dict
    validate_name(name: 'str') → None
    validate_property_name(
        property_name: 'str',
        entity_type: 'str',
        resource_type: 'str' = None
    ) → bool

    Host

    Template for modeling access to host machines with accounts, groups, credentials, and privileges

    Use this template to model who can sign in to host machines, such as Linux and Windows servers, and what they can do there, using the Open Authorization API. The Host template captures the accounts and groups on each host, the credentials that authenticate as those accounts, and the privileges that principals hold on the host and on services or commands inside it.

    Available starting with Veza v2026.10.19. This page describes the template as of that release. Earlier releases don't set the host_resource_type property on resources.

    Choose this template over the Custom Application template when the governed system is a machine rather than an application. Accounts, groups, and credentials belong to one host, so root on two hosts is two separate accounts, each with its own last login and active state. Grants can name principals from an identity provider directly, so a directory group allowed to sign in needs no local definition.

    The template models the following entities:

    • Environment - a group of hosts that share configuration, such as the identity providers that supply their principals

    • Host - a single machine

      • Users - accounts on the host, and directory users granted access without a local account

      • Groups - groups on the host, and directory groups granted access without a local definition

      • Credentials - ways of authenticating as an account on the host, such as an SSH key

      • Resources

    • Privilege definitions - the privileges that grants refer to, declared once for the whole submission

    A can define additional properties for hosts, users, groups, and resources.

    In Veza, a submission produces these entities and relationships. Identity provider users and groups, drawn with dashed lines, are created by the identity provider's own integration, not by this template. See .

    To use the Host template, set the template type to host when creating a new data provider:

    Host providers can be created only through the API, not in the Veza UI. After the first push, the integration's overview shows the host entities.

    This template has two submission modes. The fields in the payload, not a flag, select the mode.

    Mode
    Send
    Do not send
    Use when

    Veza rejects a payload that does any of the following:

    • Sends environment while any host sets environment_id

    • Omits environment while any host lacks environment_id

    • Sends neither environment nor any hosts

    An environment is shared across the data sources of a provider. Submit it from exactly one data source. Veza keys the environment to the data source that submits it, so an environment submitted from two data sources appears twice.

    In single host mode, each machine that reports for itself needs its own data source, because every push replaces everything that data source contributed before. One more data source submits the environment. A collector that reports for several machines can submit them as hosts in one payload, each with its own environment_id. A data source that supplies only the environment sends environment with no hosts. After both are pushed, Veza joins each host to the environment whose id matches the host's environment_id, so push order does not matter. Until a data source on the same provider submits the environment, the hosts that name it have no link to an environment.

    identity_provider_types on the environment applies only to hosts submitted in the same payload. Hosts submitted in single host mode are matched against every supported identity provider type. See .

    On a Linux server, most access is configured in local files. Accounts are defined in /etc/passwd and groups in /etc/group. SSH keys in each account's ~/.ssh/authorized_keys let their holders sign in as that account, and rules in sudoers let users and groups raise their privileges, either on the whole machine or for particular commands and services. A collector that reads these files maps accounts to users, groups to groups, keys to credentials, and sign-in and sudo rules to grants. The single host sample is the output of such a collector.

    The following samples model three Linux setups: a two-host fleet submitted centrally, one machine submitting for itself, and a bastion host where most access is granted to directory principals.

    Field
    Type
    Description

    The following fields are limited to 512 characters:

    • id and name of environments, hosts, users, groups, credentials, and resources

    • An environment's description

    • A host's platform, version, ip_address

    Veza parses the payload strictly, so a field this template does not define causes the push to fail. This template has no tags field.

    Most objects also accept an operation field. It has no effect, because this template does not support incremental updates.

    The environment groups hosts that share configuration. Send it in centralized mode, or from the data source that supplies the environment for single host submissions.

    Field
    Type
    Description

    identity_provider_types accepts any, active_directory, azure_ad, custom, google_workspace, okta, and one_login.

    A host is a single machine. Its users, groups, credentials, resources, and grants are nested inside it, and every reference between them resolves within that host.

    Field
    Type
    Description

    User, group, and credential IDs need only be unique within their host. Resource IDs need only be unique within their host and resource type.

    A user is an account on the host, or a directory user granted access to the host without a local account. Group membership is declared on the user.

    Field
    Type
    Description

    is_local indicates whether an account exists on the machine. identities names the directory user an entry represents:

    Veza infers no link from an account name. A local account named alice is not correlated to alice@example.com unless the entry lists that identity in identities or an matches them. A person can also reach a local account through a whose holders names their directory identity.

    last_login_at describes one person's sign-ins to one host, so it is set on the host's user rather than on the identity provider user. To record it for a directory user with no local account, submit a user entry with is_local set to false and the person's identity.

    A group is a group on the host, or a directory group granted access without a local definition.

    Field
    Type
    Description

    A member can be another group on the same host, or a directory group with no local definition. Group nesting is mainly a Windows concept, where a local group can contain a domain group. UNIX groups do not nest, so a Linux collector usually omits member_groups.

    Field
    Type
    Description

    A credential is a way of authenticating as an account on the host, such as an SSH key or a Kerberos principal. It carries no privileges of its own. It identifies which account its holder becomes.

    A credential has no field for key material or password hashes. It records that a credential exists, its type, which account it authenticates as, and who holds it.

    Field
    Type
    Description

    Credentials do not accept custom properties.

    Holders record which people hold keys to a shared account. A holder is often a directory identity with no account on the host.

    Field
    Type
    Description

    A holder with is_local set to false is linked to the matching identity provider user. A holder with is_local set to true is recorded on the credential, but Veza creates no relationship for it. Veza rejects a credential that names assumes_user and also lists a holder with is_local set to true.

    A resource is something inside a host that a privilege can apply to, rather than the host as a whole. Grants refer to a resource as <resource_type>.<id>, such as service.postgresql.

    Field
    Type
    Description

    Because the resource type cannot contain a dot, everything before the first dot in a reference is the type, and the rest is the ID. A systemd unit such as postgresql.service is referenced as service.postgresql.service.

    File and folder resources, and resources nested inside other resources, are not supported. To model permissions on shares and folders, use the .

    Each privilege is defined once, at the top level of the payload, and referenced by name wherever it is granted. The collector chooses privilege names, so it can represent any privilege, such as the right to sign in, to run sudo, or to restart a service.

    Field
    Type
    Description

    privilege_type accepts DataRead, DataWrite, DataCreate, DataDelete, MetadataRead, MetadataWrite, MetadataCreate, MetadataDelete, NonData, and Uncategorized. Veza uses these canonical types to compare access across integrations, such as a privilege called sudo-all on a host and one called

    Privilege definitions create no entities of their own. They supply the names and permission types that appear on each grant.

    identity_to_privileges is set on each host and lists which principals hold which privileges on the host and on the resources inside it. This template expresses grants only and cannot express a rule that denies access.

    Field
    Type
    Description

    A grant applies to the host when apply_to_host is true or when it names no resources. It applies to each resource it names. One grant can therefore cover the host, particular resources, or both.

    An entry in privileges can be a bare name, or an object with a name key, such as {"name": "sudo-all", "no_password": true}. Veza accepts other keys in the object but records only name.

    A grant with is_local set to false names a principal that belongs to an identity provider, such as an Active Directory group allowed by sshd_config. It does not need a matching entry in the host's users or groups.

    A Host submission names identity provider principals in four places:

    • identities on a user, linking the entry to the identity provider users it represents

    • identities on a group, and member_groups entries with is_local set to false, linking to identity provider groups

    • holders

    Veza matches these values against the integrations for the identity provider types the environment allows. Matching is case-insensitive. The attributes a value can match depend on the identity provider:

    Identity provider type
    Users match on
    Groups match on

    An Active Directory group must be named by its distinguished name. A sudoers rule for %linux-admins is submitted as CN=linux-admins,OU=Groups,DC=example,DC=com, not as linux-admins.

    Veza makes these links when the host's data source is pushed. If an identity provider integration is added later, hosts already submitted gain the missing links at their next push. Until then, a grant to a directory principal has no principal attached. A grant with no principal attached can also mean that the named identity does not exist.

    Veza resolves the members of an identity provider group only if that provider's integration supplies the group's membership.

    Host users and groups can be the destination of an , but a Host provider cannot be a mapping source. An identity mapping links a local user or group to an identity provider user or group when the payload lists none in identities.

    A Unique ID property matcher reads identity_unique_id, which Veza sets from the first value in identities on any user or group that lists one. A user or group with no identities has no identity_unique_id. To map one, match on a Property such as name, on a Custom Property, or with a Template.

    The following tables cover common ways a person gains access to a Linux or Windows host, and how to express each one. Not expressible means the Host model has no way to represent the case, such as a deny rule or access that no principal holds. Not supported means the template has no field for the case, or Veza rejects it.

    Case
    Where it is configured
    How to express it
    Case
    Where it is configured
    How to express it
    Case
    Where it is configured
    How to express it
    Case
    Where it is configured
    How to express it

    Each submission produces the following entity types:

    Entity type
    Represents
    One per

    A grant produces one Custom Host Privilege for each target it applies to. A grant that applies to the host and names two resources produces three, each carrying the same privilege names.

    Every entity type except Custom Host Privilege has a unique_id property holding the id from the payload. A Custom Host User or Custom Host Group that lists identities also has identity_unique_id, holding the first value. A Custom Host Resource also has host_resource_type, holding the resource_type from the payload, so queries can filter resources by kind. Veza sets all three properties. None of them is a payload field, and a push that includes one fails.

    In Query Builder, these entity types connect as follows:

    • A Custom Host Environment contains its Custom Hosts, and each Custom Host contains its Custom Host Users, Custom Host Groups, and Custom Host Resources.

    • A Custom Host User, a contained Custom Host Group, or an identity provider group can be a member of a Custom Host Group.

    • A Custom Host Credential or an identity provider user can assume a Custom Host User, and an identity provider group can assume a Custom Host Group, including principals matched by an .

    • An identity provider user connects to the Custom Host Credentials it holds.

    Custom properties attach additional metadata to host entities. Define properties in the custom_property_definition object, then set values on individual entities.

    Scope
    Description

    Property types are STRING, NUMBER, BOOLEAN, TIMESTAMP, and STRING_LIST, and property values must match their declared type. Property names can contain letters, digits, and underscores, and must begin with a letter. Uppercase letters are accepted and stored in lowercase, so two names that differ only in letter case are rejected. Environments, credentials, and privilege definitions do not accept custom properties. See for more detail.

    To create the OAA provider and push data:

    1. Create the provider with the host template type:

    2. Create a data source on the provider:

    3. Push the payload to the data source:

      The push endpoint requires the payload as a JSON-encoded string in the json_data field. jq -Rs . reads payload.json

    In single host mode, create a data source for each machine that reports for itself, plus exactly one data source that supplies the environment, and push each independently.

    Updates follow the same push workflow. Anything missing from a push is removed, so a host belongs to exactly one data source, and two data sources cannot each describe part of the same host. For a centralized payload too large for a single request, use .

    To build the payload in Python, use the HostProvider class in the oaaclient SDK, version 1.2.2 or later. See the .

    - objects inside the host that a privilege can apply to, such as a service or a command
  • Identity-to-privilege grants - which principals hold which privileges on the host and its resources

  • array

    Array of . Optional, but every privilege a grant names must be defined here

    custom_property_definition

    object

    Optional. Defines custom properties for hosts, users, groups, and resources. See

    incremental_change

    boolean

    Optional. Must be false or omitted. This template does not support incremental updates

    , and
    environment_id
  • A group's group_type

  • A credential's credential_type

  • array

    Optional. The identity provider types Veza searches to resolve the identities this submission names. When absent or empty, Veza searches every type

    operation

    string

    Optional. Has no effect

    version

    string

    Optional. Operating system version

    ip_address

    string

    Optional. IP address of the host

    environment_id

    string

    Required in single host mode, and must be absent in centralized mode. The id of the environment this host belongs to

    custom_properties

    dictionary

    Optional. validated against host_properties

    users

    array

    Optional. Array of objects

    groups

    array

    Optional. Array of objects

    credentials

    array

    Optional. Array of objects

    resources

    array

    Optional. Array of objects

    identity_to_privileges

    array

    Optional. Array of . Grants are declared only here

    operation

    string

    Optional. Has no effect

    array

    The identity provider users this entry represents. Required when is_local is false. Optional when is_local is true, where it links the local account to the person known to use it. Takes a list because more than one person can use one account. See

    identity_type

    string

    Optional. human or nonhuman, case-insensitive. Defaults to human

    is_active

    boolean

    Optional. Whether the account is active. Omitting it records the account as inactive

    last_login_at

    string

    Optional. RFC 3339 timestamp of when this account last signed in to this host

    groups

    array

    Optional. Group references as {"id": "group_id"} objects. Each must name a group declared on the same host

    custom_properties

    dictionary

    Optional. validated against user_properties

    operation

    string

    Optional. Has no effect

    boolean

    Required. true for a group defined on the host itself. false for a directory group granted access without a local definition

    identities

    array

    The identity provider groups this group corresponds to. Required when is_local is false. Optional when is_local is true, where it links the local group to a directory group

    member_groups

    array

    Optional. Array of references for the groups this group contains

    custom_properties

    dictionary

    Optional. validated against group_properties

    operation

    string

    Optional. Has no effect

    assumes_user

    object

    Optional. The account this credential authenticates as, given as {"id": "user_id"}. Must name a user declared on the same host. A credential with assumes_user cannot list a holder with is_local set to true

    holders

    array

    Optional. Array of references for the identities known to hold the credential

    created_at

    string

    Optional. RFC 3339 timestamp of when the credential was created

    last_used_at

    string

    Optional. RFC 3339 timestamp of when the credential was last used

    is_active

    boolean

    Optional. Whether the credential is active. Omitting it records the credential as inactive

    can_expire

    boolean

    Optional. Whether the credential can expire

    expires_at

    string

    Optional. RFC 3339 timestamp of when the credential expires

    operation

    string

    Optional. Has no effect

    dictionary

    Optional. validated against resource_properties

    operation

    string

    Optional. Has no effect

    read
    in another system.

    array

    Optional. The privilege names granted. Each must appear in the top-level privileges definitions

    apply_to_host

    boolean

    Optional. Whether the privileges apply to the host itself. A grant that names no resources applies to the host either way

    resources

    array

    Optional. Resources on this host that the privileges apply to, each as <resource_type>.<id>. Each must name a resource declared on the same host

    operation

    string

    Optional. Has no effect

    entries with
    is_local
    set to
    false
    , linking a credential to the identity provider users who hold it
  • Grants with is_local set to false, linking a directory user or group directly to the privileges it holds

  • Email address or identity provider ID

    Name or email address

    one_login

    Identity provider ID or email address

    Not matched

    custom

    Identity provider ID or email address

    Identity provider ID only

    A Kerberos principal permitted to become a local account

    ~/.k5login

    A credential with credential_type set to kerberos_principal, listing the principal's holders in holders

    Sign-in permitted to a local group

    sshd_config AllowGroups

    A grant to that group

    Sign-in permitted to a directory group

    sshd_config, sssd.conf simple_allow_groups

    A grant with is_local set to false

    A directory user permitted by name, with no local account

    The host's own configuration

    A user with is_local set to false and identities

    Sign-in permitted through PAM

    /etc/security/access.conf

    A grant to the named principal

    An account that exists but cannot sign in

    nologin shell, locked password, expiry

    is_active set to false on the user

    Access decided by the directory rather than the host

    FreeIPA host-based access control, Active Directory userWorkstations

    The collector reads the rules from the directory and submits them as grants. The host has no readable copy of the rules

    Sign-in denied to a user or group

    DenyUsers, DenyGroups, access.conf - entries

    Not expressible. The payload carries grants only

    An SSH key confined to a single command

    command="..." in authorized_keys

    Not supported. No field records the restriction

    A certificate principal permitted to become an account

    AuthorizedPrincipalsFile with an SSH certificate authority

    Not supported

    A key held by someone who also has an account on this host

    authorized_keys

    Not supported. Veza rejects a credential that names assumes_user and a holder with is_local set to true. Name the holder by their directory identity instead

    Membership in a group that is effectively root

    docker, wheel, adm, disk in /etc/group

    A grant to that group. Its members receive the privilege through group membership

    Sudo rules served from the directory

    sudoers: files sss in nsswitch.conf

    The collector obtains the rules and submits them as grants

    Sudo rules that apply only to some hosts

    alice WEBSERVERS=(ALL) ALL

    The collector resolves which rules apply to each host

    Sudo that requires no password

    NOPASSWD:

    Not supported. Veza does not distinguish it from sudo that requires a password

    Sudo performed as an account other than root

    alice ALL=(www-data) ...

    Not supported. No field records which account is assumed

    Sudo with a program excluded

    ALL, !/usr/bin/su

    Not expressible. The payload carries grants only

    Switching to another account with that account's password

    su

    Not supported

    A program that runs as its owner regardless of who invokes it

    setuid and setgid bits

    Not expressible. There is no principal to grant it to

    A program granted a specific kernel capability

    getcap, capability.conf

    Not expressible. There is no principal to grant it to

    The Remote Desktop Users group

    A grant to that group

    Remote management access

    The Remote Management Users group

    A grant to that group

    A service or scheduled task configured to run as a particular account

    Service or task configuration

    Not expressible. The model does not represent software as a principal

    NTFS access control lists

    Not supported. For shares and folders, see the

    A group on a host, or a directory group granted access to it

    Host and group

    Custom Host Credential

    A way of authenticating as an account

    Host and credential

    Custom Host Resource

    A service, command, or other resource inside a host

    Host and resource

    Custom Host Privilege

    One principal's privileges on one target

    Principal and target

    A Custom Host User, a Custom Host Group, or an identity provider user or group connects to the Custom Host Privileges it holds, and each Custom Host Privilege connects to the Custom Host or Custom Host Resource it applies to.

    and escapes it as a JSON string.
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"MyHosts","custom_template":"host"}'

    Centralized

    environment and hosts

    environment_id on any host

    A system with a view of the whole fleet, such as an inventory system or a fleet scanner, submits the environment and every host in it

    Single host

    hosts, with environment_id on every host

    environment

    An agent running on each machine submits only that machine

    host_type

    string

    Required. The kind of host being described, such as linux or windows. Can contain only letters, digits, spaces, underscores, and hyphens. Recorded as a property on every entity the submission produces

    environment

    object

    The environment object. Required in centralized mode, and must be absent in single host mode

    hosts

    array

    Array of host objects. Required in single host mode. A centralized data source that supplies only the environment can omit it

    "environment": {
      "id": "prod-linux-fleet",
      "name": "Production Linux Fleet",
      "description": "Production web and database servers",
      "identity_provider_types": ["okta"]
    }

    id

    string

    Required. Identifier for the environment. Single host submissions refer to it in environment_id

    name

    string

    Required. Display name for the environment

    description

    string

    Optional. Description shown in Veza entity details

    "hosts": [
      {
        "id": "web-01",
        "name": "web-01.prod.example.com",
        "platform": "linux",
        "version": "Ubuntu 22.04.4 LTS",
        "ip_address": "10.0.1.11",
        "custom_properties": {},
        "users": [],
        "groups": [],
        "credentials": [],
        "resources": [],
        "identity_to_privileges": []
      }
    ]

    id

    string

    Required. Identifier for the host, unique within the payload

    name

    string

    Required. Display name for the host, such as its fully qualified domain name

    platform

    string

    Optional. Operating system family, such as linux

    "users": [
      {
        "id": "alice",
        "name": "alice",
        "is_local": true,
        "is_active": true,
        "identity_type": "human",
        "last_login_at": "2026-09-24T09:14:00Z",
        "groups": [{"id": "wheel"}],
        "custom_properties": {}
      }
    ]

    id

    string

    Required. Identifier for the user, unique within the host

    name

    string

    Required. Display name for the user

    is_local

    boolean

    Required. true for an account configured on the host itself. false for a directory user granted access without a local account, such as an Active Directory or SSSD identity allowed by sshd_config or named in sudoers

    is_local

    identities

    Meaning

    true

    absent

    An account on the host with no link to a person, such as root

    true

    present

    An account on the host that the collector knows belongs to a person, such as alice listing alice@example.com

    false

    present

    A directory user with no account on this host, named in its configuration or seen in a login record

    false

    absent

    "groups": [
      {
        "id": "wheel",
        "name": "wheel",
        "group_type": "security",
        "is_local": true,
        "member_groups": [
          {"id": "linux-admins", "is_local": false}
        ],
        "custom_properties": {}
      },
      {
        "id": "linux-admins",
        "name": "linux-admins",
        "is_local": false,
        "identities": ["linux-admins"]
      }
    ]

    id

    string

    Required. Identifier for the group, unique within the host

    name

    string

    Required. Display name for the group

    group_type

    string

    Optional. The kind of group, for platforms that have more than one, such as security

    id

    string

    The member group. With is_local set to true, the id of a group declared on the same host. Otherwise the directory group's identity, resolved against the identity provider

    is_local

    boolean

    Optional. Whether the member is a group declared on this host. Defaults to false

    operation

    string

    Optional. Has no effect

    "credentials": [
      {
        "id": "key-root-shared",
        "name": "shared root key",
        "credential_type": "ssh_key",
        "assumes_user": {"id": "root"},
        "holders": [
          {"id": "alice@example.com", "is_local": false},
          {"id": "carol@example.com", "is_local": false}
        ],
        "is_active": true,
        "can_expire": false,
        "created_at": "2026-01-04T00:00:00Z",
        "last_used_at": "2026-09-24T02:00:00Z"
      }
    ]

    id

    string

    Required. Identifier for the credential, unique within the host

    name

    string

    Required. Display name for the credential

    credential_type

    string

    Optional. The kind of credential, such as ssh_key or kerberos_principal

    id

    string

    The holder. With is_local set to true, the id of a user declared on the same host. Otherwise the holder's identity, resolved against the identity provider

    is_local

    boolean

    Optional. Whether the holder is a user declared on this host. Defaults to false

    "resources": [
      {
        "id": "postgresql",
        "name": "postgresql",
        "resource_type": "service",
        "custom_properties": {
          "listen_port": 5432
        }
      },
      {
        "id": "rsync",
        "name": "/usr/bin/rsync",
        "resource_type": "command"
      }
    ]

    id

    string

    Required. Identifier for the resource, unique within the host and resource type. Can contain dots

    name

    string

    Required. Display name for the resource

    resource_type

    string

    Required. The kind of resource, chosen by the collector, such as service or command. Must not contain a dot or a colon

    "privileges": [
      {
        "name": "sudo-all",
        "description": "Unrestricted sudo",
        "privilege_type": ["DataRead", "DataWrite", "DataCreate", "DataDelete", "MetadataRead", "MetadataWrite"]
      }
    ]

    name

    string

    Required. The name grants refer to

    description

    string

    Optional. Description of the privilege

    privilege_type

    array

    Optional. The canonical permission types this privilege confers. Without it, the privilege confers no canonical permission types

    "identity_to_privileges": [
      {
        "id": "wheel",
        "grantee_type": "group",
        "is_local": true,
        "privileges": ["sudo-all"],
        "apply_to_host": true
      },
      {
        "id": "deploy",
        "grantee_type": "user",
        "is_local": true,
        "privileges": ["restart"],
        "apply_to_host": true,
        "resources": ["service.postgresql", "command.rsync"]
      },
      {
        "id": "linux-admins",
        "grantee_type": "group",
        "is_local": false,
        "privileges": ["ssh-login"],
        "apply_to_host": true
      }
    ]

    id

    string

    Required. The principal. With is_local set to true, the id of a user or group declared on the same host. Otherwise the identity of a directory principal

    grantee_type

    string

    Required. user or group

    is_local

    boolean

    Optional. Whether the principal is declared on this host. Defaults to false, so set it to true for local users and groups

    active_directory

    User principal name, account name, distinguished name, or email address

    Distinguished name only

    azure_ad

    User principal name, onPremisesSamAccountName, identity provider ID, or email address

    Name, principal name, or identity provider ID

    okta

    Login, identity provider ID, or email address

    Name or identity provider ID

    A local account with a local password

    /etc/passwd, /etc/shadow

    A user with is_local set to true

    An SSH key on a personal account

    ~/.ssh/authorized_keys

    A credential whose assumes_user is that user

    Several people holding keys to one shared account, such as root

    authorized_keys

    One credential per key, with everyone who holds that key listed in holders

    Unrestricted sudo for a user or a group

    sudoers, sudoers.d

    A grant with apply_to_host set to true

    Sudo limited to particular programs

    alice ALL=(ALL) /usr/bin/rsync

    A grant on a command resource

    Sudo limited to an action on a service

    systemctl restart postgresql

    A grant on a service resource

    Membership in the local Administrators group

    Local groups

    A grant to that group. Its members receive the privilege through group membership

    A local or domain group placed inside a local group

    Local groups

    member_groups on the containing group

    Rights such as Log on as a service, Back up files and directories, or Debug programs

    Local security policy

    Grants. The collector chooses the privilege names, so any right can be expressed

    Control of a service through a policy rule

    /etc/polkit-1/rules.d

    A grant on a service resource

    Permission to schedule work

    cron.allow, cron.deny

    A grant with apply_to_host set to true

    Permissions on a file or directory

    getfacl, mode bits

    Not supported. For folders, see the File System template

    Custom Host Environment

    A group of hosts sharing configuration

    Environment

    Custom Host

    A single machine. Privileges can apply to it directly

    Host

    Custom Host User

    An account on a host, or a directory user granted access to it

    Host and user

    "custom_property_definition": {
      "host_properties": {
        "datacenter": "STRING",
        "last_audited_at": "TIMESTAMP"
      },
      "user_properties": {
        "is_service_account": "BOOLEAN"
      },
      "group_properties": {
        "owner": "STRING",
        "tags": "STRING_LIST"
      },
      "resource_properties": {
        "listen_port": "NUMBER"
      }
    }

    host_properties

    Custom properties for host entities

    user_properties

    Custom properties for user entities

    group_properties

    Custom properties for group entities

    resource_properties

    Custom properties for resource entities

    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"MyHosts","custom_template":"host"}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"name":"prod_linux_fleet"}'
    curl -X POST "https://{VEZA_URL}/api/v1/providers/custom/{PROVIDER_ID}/datasources/{DATASOURCE_ID}:push" \
    -H "authorization: Bearer {API_KEY}" \
    -H "Content-Type: application/json" \
    --data "{\"json_data\": $(jq -Rs . payload.json)}"

    This template does not support incremental updates. Veza rejects a push with incremental_change set to true. Every push replaces everything that data source contributed before.

    Choosing a submission mode

    Sample payloads

    Real-world example: Linux servers

    Centralized: a Linux fleet with two hosts

    This example submits an environment and two hosts, web-01 and db-01, in one payload. It shows local users and groups, SSH keys, and a shared key to root held by two people. It also shows privileges on the host, a service, and a command, and custom properties at every supported scope.

    {
      "host_type": "linux",
      "custom_property_definition": {
        "host_properties": {
          "datacenter": "STRING",
          "patch_group": "STRING",
          "last_audited_at": "TIMESTAMP"
        },
        "user_properties": {
          "cost_center": "STRING",
          "is_service_account": "BOOLEAN"
        },
        "group_properties": {
          "owner": "STRING",
          "tags": "STRING_LIST"
        },
        "resource_properties": {
          "listen_port": "NUMBER"
        }
      },
      "environment": {
        "id": "prod-linux-fleet",
        "name": "Production Linux Fleet",
        "identity_provider_types": [
          "okta"
        ]
      },
      "privileges": [
        {
          "name": "ssh-login",
          "description": "May open an interactive session",
          "privilege_type": [
            "NonData"
          ]
        },
        {
          "name": "sudo-all",
          "description": "Unrestricted sudo",
          "privilege_type": [
            "DataRead",
            "DataWrite",
            "DataCreate",
            "DataDelete",
            "MetadataRead",
            "MetadataWrite"
          ]
        },
        {
          "name": "restart",
          "description": "May restart a service",
          "privilege_type": [
            "NonData"
          ]
        },
        {
          "name": "read-logs",
          "description": "May read service logs",
          "privilege_type": [
            "DataRead"
          ]
        }
      ],
      "hosts": [
        {
          "id": "web-01",
          "name": "web-01.prod.example.com",
          "platform": "linux",
          "version": "Ubuntu 22.04.4 LTS",
          "ip_address": "10.0.1.11",
          "custom_properties": {
            "datacenter": "iad1",
            "patch_group": "weekly",
            "last_audited_at": "2026-09-01T00:00:00Z"
          },
          "users": [
            {
              "id": "root",
              "name": "root",
              "is_local": true,
              "is_active": true,
              "identity_type": "nonhuman",
              "groups": [
                {
                  "id": "wheel"
                }
              ]
            },
            {
              "id": "alice",
              "identity_type": "human",
              "name": "alice",
              "is_local": true,
              "is_active": true,
              "identities": [
                "alice@example.com"
              ],
              "last_login_at": "2026-09-24T09:14:00Z",
              "groups": [
                {
                  "id": "wheel"
                },
                {
                  "id": "developers"
                }
              ],
              "custom_properties": {
                "cost_center": "eng-platform",
                "is_service_account": false
              }
            },
            {
              "id": "deploy",
              "name": "deploy",
              "is_local": true,
              "is_active": true,
              "custom_properties": {
                "is_service_account": true
              }
            }
          ],
          "groups": [
            {
              "id": "wheel",
              "name": "wheel",
              "is_local": true,
              "group_type": "security",
              "custom_properties": {
                "owner": "platform-team",
                "tags": [
                  "production",
                  "on-call"
                ]
              }
            },
            {
              "id": "developers",
              "name": "developers",
              "is_local": true,
              "group_type": "security"
            }
          ],
          "credentials": [
            {
              "id": "key-alice",
              "name": "alice laptop key",
              "credential_type": "ssh_key",
              "assumes_user": {
                "id": "alice"
              },
              "is_active": true,
              "can_expire": false,
              "created_at": "2026-01-04T00:00:00Z",
              "last_used_at": "2026-09-24T02:00:00Z"
            },
            {
              "id": "key-deploy-ci",
              "name": "CI deploy key",
              "credential_type": "ssh_key",
              "assumes_user": {
                "id": "deploy"
              },
              "is_active": true,
              "can_expire": false,
              "holders": [
                {
                  "id": "ci-bot@example.com",
                  "is_local": false
                }
              ]
            }
          ],
          "resources": [
            {
              "id": "postgresql",
              "name": "postgresql",
              "resource_type": "service",
              "custom_properties": {
                "listen_port": 5432
              }
            },
            {
              "id": "rsync",
              "name": "/usr/bin/rsync",
              "resource_type": "command"
            }
          ],
          "identity_to_privileges": [
            {
              "id": "wheel",
              "grantee_type": "group",
              "is_local": true,
              "privileges": [
                "sudo-all"
              ],
              "apply_to_host": true
            },
            {
              "id": "root",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                "ssh-login"
              ]
            },
            {
              "id": "alice",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                "ssh-login"
              ],
              "apply_to_host": true
            },
            {
              "id": "developers",
              "grantee_type": "group",
              "is_local": true,
              "privileges": [
                "restart",
                "read-logs"
              ],
              "resources": [
                "service.postgresql"
              ]
            },
            {
              "id": "deploy",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                "restart"
              ],
              "resources": [
                "service.postgresql",
                "command.rsync"
              ],
              "apply_to_host": true
            }
          ]
        },
        {
          "id": "db-01",
          "name": "db-01.prod.example.com",
          "platform": "linux",
          "version": "Ubuntu 22.04.4 LTS",
          "ip_address": "10.0.1.21",
          "custom_properties": {
            "datacenter": "iad1",
            "patch_group": "monthly",
            "last_audited_at": "2026-08-15T00:00:00Z"
          },
          "users": [
            {
              "id": "root",
              "name": "root",
              "is_local": true,
              "is_active": true
            },
            {
              "id": "postgres",
              "identity_type": "NonHuman",
              "name": "postgres",
              "is_local": true,
              "is_active": true,
              "custom_properties": {
                "is_service_account": true
              }
            },
            {
              "id": "bob",
              "name": "bob",
              "is_local": true,
              "is_active": false,
              "identities": [
                "bob@example.com"
              ]
            }
          ],
          "groups": [
            {
              "id": "wheel",
              "name": "wheel",
              "is_local": true,
              "group_type": "security"
            },
            {
              "id": "dba",
              "name": "dba",
              "is_local": true,
              "group_type": "security",
              "custom_properties": {
                "owner": "data-team",
                "tags": [
                  "production"
                ]
              }
            }
          ],
          "credentials": [
            {
              "id": "key-root-shared",
              "name": "shared root key",
              "credential_type": "ssh_key",
              "assumes_user": {
                "id": "root"
              },
              "is_active": true,
              "can_expire": false,
              "holders": [
                {
                  "id": "alice@example.com",
                  "is_local": false
                },
                {
                  "id": "carol@example.com",
                  "is_local": false
                }
              ]
            }
          ],
          "resources": [
            {
              "id": "postgresql",
              "name": "postgresql",
              "resource_type": "service",
              "custom_properties": {
                "listen_port": 5432
              }
            }
          ],
          "identity_to_privileges": [
            {
              "id": "wheel",
              "grantee_type": "group",
              "is_local": true,
              "privileges": [
                "sudo-all"
              ],
              "apply_to_host": true
            },
            {
              "id": "dba",
              "grantee_type": "group",
              "is_local": true,
              "privileges": [
                "restart",
                "read-logs"
              ],
              "resources": [
                "service.postgresql"
              ]
            },
            {
              "id": "bob",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                "ssh-login"
              ],
              "apply_to_host": true
            }
          ]
        }
      ]
    }

    Key patterns from this example:

    • Accounts belong to one host. root and wheel appear on both hosts and become separate entities. Each root account has its own is_active and last_login_at.

    • A local account can name the person who uses it. alice on web-01 and bob on db-01 are local accounts that list the people who use them in identities, so Veza links each one to the matching identity provider user. root and deploy list no identity and stay unlinked unless an matches them.

    • Holders distinguish people sharing an account. The key-root-shared credential on db-01 authenticates as root and records that alice@example.com and carol@example.com hold it.

    • A grant can target the host, resources, or both. The deploy grant applies restart to the host and to service.postgresql and command.rsync.

    • identity_type values are case-insensitive. postgres declares NonHuman, which is read as nonhuman.

    Single host: one machine reporting for itself

    An agent running on app-07 submits this payload. It carries no environment. Instead, the host names its environment in environment_id, which must match the id of an environment that another data source on the same provider submits, such as prod-linux-fleet in the centralized example.

    A collector generated this payload, without edits, from a sample server's /etc/passwd, /etc/group, /etc/shadow, authorized_keys, sudoers, sshd_config, and sssd.conf files.

    Key patterns from this example:

    • System accounts are submitted too. daemon, postgres, and svc_deploy are accounts with identity_type set to nonhuman.

    • The collector decides whether an account is active. Linux records no such field. This collector marks an account inactive when its password is locked and no SSH key signs in as it, so carol is inactive even though sshd_config

    Centralized: a bastion host with directory-backed principals

    This example models a bastion host where most access is granted to directory principals. Because identity_provider_types is custom, identities resolve against a Custom Identity Provider.

    {
      "host_type": "linux",
      "environment": {
        "id": "corp-linux-fleet",
        "name": "Corporate Linux Fleet",
        "identity_provider_types": [
          "custom"
        ]
      },
      "privileges": [
        {
          "name": "ssh-login",
          "description": "May open an interactive session",
          "privilege_type": [
            "NonData"
          ]
        },
        {
          "name": "sudo-all",
          "description": "Unrestricted sudo",
          "privilege_type": [
            "DataRead",
            "DataWrite",
            "DataCreate",
            "DataDelete",
            "MetadataRead",
            "MetadataWrite"
          ]
        }
      ],
      "hosts": [
        {
          "id": "bastion-01",
          "name": "bastion-01.corp.example.com",
          "platform": "linux",
          "version": "RHEL 9.4",
          "ip_address": "10.10.0.5",
          "users": [
            {
              "id": "root",
              "name": "root",
              "is_local": true,
              "is_active": true
            },
            {
              "id": "svc-backup",
              "identity_type": "nonhuman",
              "name": "svc-backup",
              "is_local": true,
              "is_active": true
            },
            {
              "id": "erin@example.com",
              "identity_type": "human",
              "name": "erin@example.com",
              "is_local": false,
              "identities": [
                "erin@example.com"
              ],
              "last_login_at": "2026-09-23T17:02:00Z"
            }
          ],
          "groups": [
            {
              "id": "wheel",
              "name": "wheel",
              "is_local": true,
              "group_type": "security",
              "member_groups": [
                {
                  "id": "linux-admins",
                  "is_local": false
                }
              ]
            },
            {
              "id": "linux-admins",
              "name": "linux-admins",
              "is_local": false,
              "identities": [
                "linux-admins"
              ]
            }
          ],
          "credentials": [
            {
              "id": "key-root-team",
              "name": "root key held by the platform team",
              "credential_type": "ssh_key",
              "assumes_user": {
                "id": "root"
              },
              "is_active": true,
              "can_expire": false,
              "holders": [
                {
                  "id": "erin@example.com",
                  "is_local": false
                },
                {
                  "id": "frank@example.com",
                  "is_local": false
                }
              ]
            },
            {
              "id": "kerb-svc-backup",
              "name": "backup kerberos principal",
              "credential_type": "kerberos_principal",
              "assumes_user": {
                "id": "svc-backup"
              },
              "is_active": true,
              "can_expire": false,
              "holders": [
                {
                  "id": "backup@CORP.EXAMPLE.COM",
                  "is_local": false
                }
              ]
            }
          ],
          "identity_to_privileges": [
            {
              "id": "wheel",
              "grantee_type": "group",
              "is_local": true,
              "privileges": [
                "sudo-all"
              ],
              "apply_to_host": true
            },
            {
              "id": "linux-admins",
              "grantee_type": "group",
              "is_local": false,
              "privileges": [
                "ssh-login"
              ],
              "apply_to_host": true
            },
            {
              "id": "erin@example.com",
              "grantee_type": "user",
              "is_local": false,
              "privileges": [
                "ssh-login"
              ],
              "apply_to_host": true
            },
            {
              "id": "contractors",
              "grantee_type": "group",
              "is_local": false,
              "privileges": [
                "ssh-login"
              ],
              "apply_to_host": true
            }
          ]
        }
      ]
    }

    Key patterns from this example:

    • A directory user can appear without a local account. erin@example.com has is_local set to false and lists the person's identity, so the payload can record when that person last signed in to this host.

    • A local group can contain a directory group. wheel lists linux-admins in member_groups with is_local set to false.

    • A grant can name a principal that the host does not declare. The contractors grant has is_local set to false and no matching group entry. Veza resolves it against the identity provider.

    • Credentials are not only SSH keys. kerb-svc-backup is a Kerberos principal permitted to become svc-backup.

    Top-level payload

    Environment

    Environment properties

    Hosts

    Host properties

    Users

    User properties

    Groups

    Group properties

    Member groups

    Credentials

    Credential properties

    Holders

    Resources

    Resource properties

    Privilege definitions

    Privilege definition properties

    Granting privileges

    Grant properties

    Correlating with identity providers

    Identity mapping

    What this template can and cannot express

    Signing in

    Raising privilege

    Windows

    Services, scheduled jobs, and files

    Entities in Veza

    Custom property definitions

    Creating and updating a host provider

    custom property definition
    Entities in Veza
    Correlating with identity providers
    identity mapping
    credential
    File System template
    identity mapping
    identity mapping
    Custom properties
    multipart upload
    Host module reference

    privileges

    identity_provider_types

    identities

    Rejected. A user with no account and no one to attribute it to

    is_local

    custom_properties

    privileges

    google_workspace

    Remote desktop access

    Permissions on a Windows file or share

    Custom Host Group

    permits her to sign in.
  • Directory principals appear only where the host names them. sshd_config and sssd.conf permit jsmith, linux-admins, and dbas, which have no local definition. Each is submitted with is_local set to false and an identity to resolve, and each holds login.

  • An omitted is_active means inactive. jsmith sets no is_active, so Veza records it as inactive.

  • One key can produce several credentials. A key in two accounts' authorized_keys signs in as each of them, so the credential ID combines the account and the key fingerprint. The key with fingerprint SHA256:F9PpGs… is in the authorized_keys of both root and alice, so it is submitted as two credentials.

  • A key that names no one has no holders. A key whose comment names nobody, such as laptop, is submitted with no holders.

  • Sudo is expressed as privileges on the host or on commands. wheel holds sudo-all on the host, written as an object whose no_password key Veza accepts but does not record. svc_deploy holds sudo-command on two command resources, one for each command its sudoers rule allows.

  • Custom properties describe the collection. sources_read on the host lists the files that were read, so a query can distinguish a host whose sudoers could not be read from a host that grants no sudo.

  • identity mapping
    privilege definitions
    Custom property definitions
    Custom properties
    user
    group
    credential
    resource
    grants
    Correlating with identity providers
    Custom properties
    member group
    Custom properties
    holder
    Custom properties
    File System template
    {
      "host_type": "linux",
      "custom_property_definition": {
        "host_properties": {
          "sources_read": "STRING_LIST",
          "collector_version": "STRING"
        },
        "user_properties": {
          "shell": "STRING",
          "password_locked": "BOOLEAN"
        },
        "group_properties": {},
        "resource_properties": {}
      },
      "privileges": [
        {
          "name": "login",
          "description": "May open an interactive session on the host",
          "privilege_type": [
            "NonData"
          ]
        },
        {
          "name": "sudo-all",
          "description": "Unrestricted sudo",
          "privilege_type": [
            "DataRead",
            "DataWrite",
            "DataCreate",
            "DataDelete",
            "MetadataRead",
            "MetadataWrite",
            "MetadataCreate",
            "MetadataDelete"
          ]
        },
        {
          "name": "sudo-command",
          "description": "May run particular commands through sudo",
          "privilege_type": [
            "NonData"
          ]
        }
      ],
      "hosts": [
        {
          "id": "app-07",
          "name": "app-07.prod.example.com",
          "platform": "linux",
          "version": "Ubuntu 22.04.4 LTS",
          "ip_address": "10.0.2.7",
          "environment_id": "prod-linux-fleet",
          "custom_properties": {
            "sources_read": [
              "accounts",
              "ssh_keys",
              "sshd_config",
              "sssd_conf",
              "sudoers"
            ],
            "collector_version": "0.1.0"
          },
          "users": [
            {
              "id": "root",
              "name": "root",
              "is_local": true,
              "identity_type": "nonhuman",
              "is_active": true,
              "custom_properties": {
                "shell": "/bin/bash",
                "password_locked": false
              },
              "groups": [
                {
                  "id": "root"
                }
              ]
            },
            {
              "id": "daemon",
              "name": "daemon",
              "is_local": true,
              "identity_type": "nonhuman",
              "is_active": false,
              "custom_properties": {
                "shell": "/usr/sbin/nologin",
                "password_locked": true
              },
              "groups": [
                {
                  "id": "daemon"
                }
              ]
            },
            {
              "id": "postgres",
              "name": "PostgreSQL administrator",
              "is_local": true,
              "identity_type": "nonhuman",
              "is_active": false,
              "custom_properties": {
                "shell": "/bin/bash",
                "password_locked": true
              },
              "groups": [
                {
                  "id": "postgres"
                }
              ]
            },
            {
              "id": "alice",
              "name": "Alice Nakamura",
              "is_local": true,
              "identity_type": "human",
              "is_active": true,
              "custom_properties": {
                "shell": "/bin/bash",
                "password_locked": false
              },
              "groups": [
                {
                  "id": "alice"
                },
                {
                  "id": "sudo"
                },
                {
                  "id": "wheel"
                }
              ]
            },
            {
              "id": "carol",
              "name": "Carol Diaz",
              "is_local": true,
              "identity_type": "human",
              "is_active": false,
              "custom_properties": {
                "shell": "/bin/bash",
                "password_locked": true
              },
              "groups": [
                {
                  "id": "carol"
                },
                {
                  "id": "wheel"
                }
              ]
            },
            {
              "id": "svc_deploy",
              "name": "Deployment service",
              "is_local": true,
              "identity_type": "nonhuman",
              "is_active": false,
              "custom_properties": {
                "shell": "/usr/sbin/nologin",
                "password_locked": true
              },
              "groups": [
                {
                  "id": "svc_deploy"
                }
              ]
            },
            {
              "id": "jsmith",
              "name": "jsmith",
              "identities": [
                "jsmith"
              ],
              "is_local": false
            }
          ],
          "groups": [
            {
              "id": "root",
              "name": "root",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "daemon",
              "name": "daemon",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "sudo",
              "name": "sudo",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "postgres",
              "name": "postgres",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "wheel",
              "name": "wheel",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "alice",
              "name": "alice",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "carol",
              "name": "carol",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "svc_deploy",
              "name": "svc_deploy",
              "group_type": "local",
              "is_local": true
            },
            {
              "id": "linux-admins",
              "name": "linux-admins",
              "group_type": "directory",
              "is_local": false,
              "identities": [
                "linux-admins"
              ]
            },
            {
              "id": "dbas",
              "name": "dbas",
              "group_type": "directory",
              "is_local": false,
              "identities": [
                "dbas"
              ]
            }
          ],
          "credentials": [
            {
              "id": "root:SHA256:AVLp5MVQPuVN21outJNeQ1jECeaGcPNchYKjWkgdrRQ",
              "name": "backup@ci.example.com",
              "credential_type": "ssh_key",
              "holders": [
                {
                  "id": "backup@ci.example.com",
                  "is_local": false
                },
                {
                  "id": "dcooper@example.com",
                  "is_local": false
                }
              ],
              "is_active": true,
              "can_expire": false,
              "assumes_user": {
                "id": "root"
              }
            },
            {
              "id": "root:SHA256:F9PpGsngzsZUNdILKaPPnVMowTBXWl43kYojRg2Y8lg",
              "name": "alice@example.com",
              "credential_type": "ssh_key",
              "holders": [
                {
                  "id": "alice@example.com",
                  "is_local": false
                }
              ],
              "is_active": true,
              "can_expire": false,
              "assumes_user": {
                "id": "root"
              }
            },
            {
              "id": "alice:SHA256:F9PpGsngzsZUNdILKaPPnVMowTBXWl43kYojRg2Y8lg",
              "name": "alice@example.com",
              "credential_type": "ssh_key",
              "holders": [
                {
                  "id": "alice@example.com",
                  "is_local": false
                }
              ],
              "is_active": true,
              "can_expire": false,
              "assumes_user": {
                "id": "alice"
              }
            },
            {
              "id": "alice:SHA256:mdjRRFt76vijB/211jtzs1JjGFJR6LVIbEqfsGAoPR4",
              "name": "laptop",
              "credential_type": "ssh_key",
              "is_active": true,
              "can_expire": false,
              "assumes_user": {
                "id": "alice"
              }
            }
          ],
          "resources": [
            {
              "id": "/usr/bin/rsync",
              "name": "/usr/bin/rsync",
              "resource_type": "command"
            },
            {
              "id": "/usr/bin/systemctl restart nginx",
              "name": "/usr/bin/systemctl restart nginx",
              "resource_type": "command"
            }
          ],
          "identity_to_privileges": [
            {
              "id": "root",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                "sudo-all"
              ],
              "apply_to_host": true
            },
            {
              "id": "sudo",
              "grantee_type": "group",
              "is_local": true,
              "privileges": [
                "sudo-all"
              ],
              "apply_to_host": true
            },
            {
              "id": "wheel",
              "grantee_type": "group",
              "is_local": true,
              "privileges": [
                {
                  "name": "sudo-all",
                  "no_password": true
                },
                "login"
              ],
              "apply_to_host": true
            },
            {
              "id": "svc_deploy",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                {
                  "name": "sudo-command",
                  "no_password": true
                }
              ],
              "resources": [
                "command./usr/bin/rsync",
                "command./usr/bin/systemctl restart nginx"
              ]
            },
            {
              "id": "linux-admins",
              "grantee_type": "group",
              "is_local": false,
              "privileges": [
                "login"
              ],
              "apply_to_host": true
            },
            {
              "id": "alice",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                "login"
              ],
              "apply_to_host": true
            },
            {
              "id": "carol",
              "grantee_type": "user",
              "is_local": true,
              "privileges": [
                "login"
              ],
              "apply_to_host": true
            },
            {
              "id": "jsmith",
              "grantee_type": "user",
              "is_local": false,
              "privileges": [
                "login"
              ],
              "apply_to_host": true
            },
            {
              "id": "dbas",
              "grantee_type": "group",
              "is_local": false,
              "privileges": [
                "login"
              ],
              "apply_to_host": true
            }
          ]
        }
      ]
    }