OAA Push API
Methods for working with Custom Data Providers and Sources
Last updated
Was this helpful?
Methods for working with Custom Data Providers and Sources
Last updated
Was this helpful?
This document provides a basic overview of the API requests for creating and updating an OAA data source. These steps and 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.
While registering sources and pushing authorization metadata with 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
).
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.
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.
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.
json_data
must contain the populated OAA template as a single JSON string (escaping any unsafe characters such as "
).
Use to register a new top-level custom provider:
Each provider needs at least one data source. Create one with
Once the data source and provider are active, publish the payload with . The request body must include the Provider ID and Data Source ID.
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.