1 of 2

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 (specifying the app name and template).
- The determines the application type of the provider's custom data sources (identity_provider or application).

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.

Authentication

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.

First Run

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.

Create a provider using the "Custom Application" template

Use to register a new top-level custom provider:

The response will return the Provider's ID, which you will need to create and manage the data sources:

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 exists before creating a new one.

Create a Data Source for the Provider

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

Push data source metadata

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

Get Custom Providers

Get Custom Data Sources

Update Custom Data Source

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.

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 Custom Provider

Creates a custom provider and returns the provider ID.

List Custom Providers

Lists all configured custom providers.

Get Custom Provider by ID

Returns details for an individual custom provider.

Delete Custom Provider

Delete a custom provider by ID.

List Custom Provider Datasources

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

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

Returns details for a single datasource.

Delete Custom Provider Datasource

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

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

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.

Push Custom Provider Datasource CSV

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.

Compression

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

Escaping unsafe characters

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:

Custom Provider Icons

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:

Create Custom Provider Icon

Upload a custom icon to display for an OAA provider.

Get Custom Provider Icon

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

Delete Custom Provider Icon

Delete the icon associated with an OAA provider.

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 Custom Provider

Creates a custom provider and returns the provider ID.

List Custom Providers

Lists all configured custom providers.

Get Custom Provider by ID

Returns details for an individual custom provider.

Delete Custom Provider

Delete a custom provider by ID.

List Custom Provider Datasources

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

Create Custom Provider Datasource

Get Datasource by ID

Returns details for a single datasource.

Delete Custom Provider Datasource

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

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

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.

Push Custom Provider Datasource CSV

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.

Compression

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

Escaping unsafe characters

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:

Custom Provider Icons

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:

Create Custom Provider Icon

Upload a custom icon to display for an OAA provider.

Get Custom Provider Icon

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

Delete Custom Provider Icon

Delete the icon associated with an OAA provider.

OAA Push API

Methods for working with Custom Data Providers and Sources

Overview

You will first register a new custom application provider with a (specifying the app name and template).
- The determines the application type of the provider's custom data sources (identity_provider or application).

Authentication

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.

First Run

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.

Create a provider using the "Custom Application" template

Use to register a new top-level custom provider:

The response will return the Provider's ID, which you will need to create and manage the data sources:

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 exists before creating a new one.

Create a Data Source for the Provider

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

Push data source metadata

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

Get Custom Providers

Get Custom Data Sources

Update Custom Data Source

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.

{ "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" ], "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" }, "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" } ] } ], "use_email": true }, "hris_provisioning_source": true } }, "secret_references": [ { "id": "text", "secret_id": "text", "vault_id": "text", "vault": { "id": "text", "name": "text", "vault_provider": "text", "insight_point_id": "text", "deleted": true } } ], "external_lifecycle_management_type": 1 } }

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: 1328 { "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" }, "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" } ] } ], "use_email": true }, "hris_provisioning_source": true } }, "secret_references": [ { "secret_id": "text", "vault_id": "text" } ], "external_lifecycle_management_type": 1 }

{ "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" ], "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" }, "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" } ] } ], "use_email": true }, "hris_provisioning_source": true } }, "secret_references": [ { "id": "text", "secret_id": "text", "vault_id": "text", "vault": { "id": "text", "name": "text", "vault_provider": "text", "insight_point_id": "text", "deleted": true } } ], "external_lifecycle_management_type": 1 } ], "next_page_token": "text", "has_more": true }

OAA Push API

hashtagOverview

hashtagAuthentication

hashtagFirst Run

hashtagCreate a provider using the "Custom Application" template

hashtagCreate a Data Source for the Provider

hashtagPush data source metadata

hashtagGet Custom Providers

hashtagGet Custom Data Sources

hashtagUpdate Custom Data Source

OAA Operations

hashtagCreate Custom Provider

hashtagList Custom Providers

hashtagGet Custom Provider by ID

hashtagDelete Custom Provider

hashtagList Custom Provider Datasources

hashtagCreate Custom Provider Datasource

hashtagGet Datasource by ID

hashtagDelete Custom Provider Datasource

hashtagPush Custom Provider Datasource

hashtagPush Custom Provider Datasource CSV

hashtagCompression

hashtagEscaping unsafe characters

hashtagCustom Provider Icons

hashtagCreate Custom Provider Icon

hashtagGet Custom Provider Icon

hashtagDelete Custom Provider Icon

OAA Operations

hashtagCreate Custom Provider

hashtagList Custom Providers

hashtagGet Custom Provider by ID

hashtagDelete Custom Provider

hashtagList Custom Provider Datasources

hashtagCreate Custom Provider Datasource

hashtagGet Datasource by ID

hashtagDelete Custom Provider Datasource

hashtagPush Custom Provider Datasource

hashtagPush Custom Provider Datasource CSV

hashtagCompression

hashtagEscaping unsafe characters

hashtagCustom Provider Icons

hashtagCreate Custom Provider Icon

hashtagGet Custom Provider Icon

hashtagDelete Custom Provider Icon

OAA Push API

hashtagOverview

hashtagAuthentication

hashtagFirst Run

hashtagCreate a provider using the "Custom Application" template

hashtagCreate a Data Source for the Provider

hashtagPush data source metadata

hashtagGet Custom Providers

hashtagGet Custom Data Sources

hashtagUpdate Custom Data Source

Overview

Authentication

First Run

Create a provider using the "Custom Application" template

Create a Data Source for the Provider

Push data source metadata

Get Custom Providers

Get Custom Data Sources

Update Custom Data Source

Create Custom Provider

List Custom Providers

Get Custom Provider by ID

Delete Custom Provider

List Custom Provider Datasources

Create Custom Provider Datasource

Get Datasource by ID

Delete Custom Provider Datasource

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

Create Custom Provider

List Custom Providers

Get Custom Provider by ID

Delete Custom Provider

List Custom Provider Datasources

Create Custom Provider Datasource

Get Datasource by ID

Delete Custom Provider Datasource

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

Overview

Authentication

First Run

Create a provider using the "Custom Application" template

Create a Data Source for the Provider

Push data source metadata

Get Custom Providers

Get Custom Data Sources

Update Custom Data Source