1 of 4

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 type of entities the provider supports (application, identity_provider, or hris).

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

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:

Unlike SCIM mode, SEND_REST_PAYLOAD does not require an OAA connector definition. REST endpoints, HTTP methods, authentication, and payloads are configured in the Lifecycle Management policy. The Insight Point associated with the data source executes the REST calls.

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 mapped to local accounts in other systems, and assigned as entity owners. Custom IdPs can also be used a source of identity for Lifecycle Management 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 Lifecycle Management 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

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.

Using the Python SDK

The oaaclient SDK provides create_provider() with an options parameter for advanced fields:

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 is required in both the request path and body.

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.

Multipart Push Custom Provider Datasource

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.

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.

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

Start the upload by sending a start request — the server creates an upload session and returns an upload_id.
Upload chunks sequentially, each base64-encoding a raw slice of the payload. Include the upload_id from step 1 and an incrementing sequence_number.

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.

API endpoint

Start request body

Field

Type

Description

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

Chunk request body

Field

Type

Description

Finalization request body

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

Field

Type

Description

Example

Using the Python SDK

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

Notes

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.

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. Contact your Veza support team to enable the INTEG_OAA_SSO_LAST_LOGIN flag for your tenant.

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

You specify the Okta Application ID (okta_app_id) for your custom application.
Veza matches your OAA local users to Okta users using a configurable matching property (set via the Veza API in Step 2).
On each data push, Veza looks up Okta SSO activity for your application and writes the last login timestamp to matching local user nodes.

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

Prerequisites

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.
Your OAA local users must have identities values that match a property on your Okta user profiles (such as email address or a custom attribute).

Setup

Step 1: Request feature enablement

Contact your Veza representative or support team and request:

Enable the INTEG_OAA_SSO_LAST_LOGIN feature flag on our tenant.

This flag is Veza-administered and cannot be self-enabled.

Step 2: Set the matching property configuration

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.

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

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: ["[email protected]"] and OktaUser nodes have login: "[email protected]", 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.

Step 3: Find your Okta application ID

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

Log in to your Okta Admin Console.
Navigate to Applications > Applications.
Select the application.
Copy the application ID from the URL (format: 0oaXXXXXXXXXXXXXXXX

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

The method depends on how you push data to Veza.

API push (JSON)

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.

CSV upload

Navigate to Integrations > Custom Application (CSV).
Enter your Okta Application ID in the Okta App ID field in the application configuration form.
Upload your CSV as usual, ensuring users have identity values that match their Okta profiles.

The Okta App ID field in the CSV configuration form is only visible when the INTEG_OAA_SSO_LAST_LOGIN feature flag is enabled on your tenant.

Verifying enrichment

After pushing data, verify enrichment is working:

Open Query Builder in Veza.
Query for your custom application's local users.
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.

Behavior notes

Matching is case-insensitive. [email protected] and [email protected] 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.

Troubleshooting

Issue

Possible cause

Resolution

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.

Multipart Push Custom Provider Datasource

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.

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.

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. Contact your Veza support team to enable the INTEG_OAA_SSO_LAST_LOGIN flag for your tenant.

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

How it works

You specify the Okta Application ID (okta_app_id) for your custom application.
Veza matches your OAA local users to Okta users using a configurable matching property (set via the Veza API in Step 2).
On each data push, Veza looks up Okta SSO activity for your application and writes the last login timestamp to matching local user nodes.

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

Prerequisites

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.
Your OAA local users must have identities values that match a property on your Okta user profiles (such as email address or a custom attribute).

Setup

Step 1: Request feature enablement

Contact your Veza representative or support team and request:

Enable the INTEG_OAA_SSO_LAST_LOGIN feature flag on our tenant.

This flag is Veza-administered and cannot be self-enabled.

Step 2: Set the matching property configuration

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.

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

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: ["[email protected]"] and OktaUser nodes have login: "[email protected]", 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.

Step 3: Find your Okta application ID

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

Log in to your Okta Admin Console.
Navigate to Applications > Applications.
Select the application.
Copy the application ID from the URL (format: 0oaXXXXXXXXXXXXXXXX

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

The method depends on how you push data to Veza.

API push (JSON)

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.

CSV upload

Navigate to Integrations > Custom Application (CSV).
Enter your Okta Application ID in the Okta App ID field in the application configuration form.
Upload your CSV as usual, ensuring users have identity values that match their Okta profiles.

The Okta App ID field in the CSV configuration form is only visible when the INTEG_OAA_SSO_LAST_LOGIN feature flag is enabled on your tenant.

Verifying enrichment

After pushing data, verify enrichment is working:

Open Query Builder in Veza.
Query for your custom application's local users.
Check the sso_last_login_at column on user nodes.

Behavior notes

Matching is case-insensitive. [email protected] and [email protected] 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.

Troubleshooting

Issue

Possible cause

Resolution

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

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

idstringRead-onlyOptional

secret_idstringOptional

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

Responses

200

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

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

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

idstringRead-onlyOptional

secret_idstringOptional

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

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

List custom providers

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

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

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

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

idstringRead-onlyOptional

secret_idstringOptional

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

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

codeinteger · int32Optional

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

messagestringOptional

@typestringOptional

The type of the serialized message.

Other propertiesanyOptional

get

/api/v1/providers/custom

get

Authorizations

AuthorizationstringRequired

Veza API key for authentication. Generate keys in Administration > API Keys.

Path parameters

idstringRequired

Responses

200

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

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

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

idstringRead-onlyOptional

secret_idstringOptional

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

default

Default error response

application/json

codeinteger · int32Optional

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

messagestringOptional

@typestringOptional

The type of the serialized message.

Other propertiesanyOptional

get

/api/v1/providers/custom/{id}

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 type of entities the provider supports (application, identity_provider, or hris).

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

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

Custom Identity Provider

This template is for modeling custom or unsupported identity providers as a source of users and groups:

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 Lifecycle Management 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

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.

Using the Python SDK

The oaaclient SDK provides create_provider() with an options parameter for advanced fields:

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 is required in both the request path and body.

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 Push API

hashtagOverview

hashtagAuthentication

hashtagFirst Run

hashtagCreate a Custom Provider

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

hashtagMultipart Push 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

Multipart Upload

hashtagOverview

hashtagHow it works

hashtagAPI endpoint

hashtagStart request body

hashtagChunk request body

hashtagFinalization request body

hashtagExample

hashtagUsing the Python SDK

hashtagNotes

Okta SSO Last Login Enrichment

hashtagHow it works

hashtagPrerequisites

hashtagSetup

hashtagStep 1: Request feature enablement

hashtagStep 2: Set the matching property configuration

hashtagStep 3: Find your Okta application ID

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

hashtagAPI push (JSON)

hashtagCSV upload

hashtagVerifying enrichment

hashtagBehavior notes

hashtagTroubleshooting

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

hashtagMultipart Push 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

Okta SSO Last Login Enrichment

hashtagHow it works

hashtagPrerequisites

hashtagSetup

hashtagStep 1: Request feature enablement

hashtagStep 2: Set the matching property configuration

hashtagStep 3: Find your Okta application ID

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

hashtagAPI push (JSON)

hashtagCSV upload

hashtagVerifying enrichment

Overview

Authentication

First Run

Create a Custom Provider

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

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

Overview

How it works

API endpoint

Start request body

Chunk request body

Finalization request body

Example

Using the Python SDK

Notes

How it works

Prerequisites

Setup

Step 1: Request feature enablement

Step 2: Set the matching property configuration

Step 3: Find your Okta application ID

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

API push (JSON)

CSV upload

Verifying enrichment

Behavior notes

Troubleshooting

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

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

How it works

Prerequisites

Setup

Step 1: Request feature enablement

Step 2: Set the matching property configuration

Step 3: Find your Okta application ID

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

API push (JSON)

CSV upload

Verifying enrichment

Behavior notes

Troubleshooting

List custom providers

Overview

How it works

API endpoint