# OAA Push API

This document provides a basic overview of the API requests for creating and updating an OAA data source. These steps and [API calls](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md) 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](/4yItIzMvkpAvMVFAamTf/developers/api/oaa.md) 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`](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#create-custom-provider) (specifying the app *name* and *template*).
  * The [**template**](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates.md) 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 [Create Datasource](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#create-custom-provider-datasource).
  * The populated template can describe additional resources and sub-resources, such as individual databases, repositories, or views.
* You can [push authorization metadata](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#push-custom-provider-datasource) for each custom **data source**.
* All custom data sources are shown on the **Configuration** > *Apps & Data Sources* menu, and can be retrieved using [List Custom Provider Datasources](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#list-custom-provider-datasources).

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 [Best Practices](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/best-practices.md) 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 [Team API key](/4yItIzMvkpAvMVFAamTf/developers/api/authentication/api-tokens.md#team-api-keys-early-access) is recommended. Provide it as the bearer auth token in the header of each request, for example:

```bash
curl -X GET "https://$VEZA_URL/api/v1/providers/custom" \
-H "authorization: Bearer $API_KEY"
```

> **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 [Create Custom Provider](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#create-custom-provider) to register a new top-level custom provider. The `custom_template` determines what kind of entities you can push to the provider.

| Template                                                                                                            | `custom_template` value | Use case                                                                        |
| ------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------- |
| [Custom Application](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/custom-application-template.md)             | `application`           | Applications and services with users, groups, roles, resources, and permissions |
| [Custom Identity Provider](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/custom-identity-provider-template.md) | `identity_provider`     | Identity sources with users, groups, domains, and app assignments               |
| [HRIS](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/templates/hris-template.md)                                         | `hris`                  | HR systems with employees, managers, and organizational groups                  |

**Custom Application provider**

This is a common configuration with broad support for modeling applications with local identities, resources, and authorization:

```bash
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"}'
```

**Custom Application with SCIM lifecycle management**

If your application exposes SCIM 2.0 endpoints, it can support automated provisioning and deprovisioning through [Veza Lifecycle Management](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/integrations/oaa-scim.md):

```bash
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"
}'
```

**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:

```bash
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"
}'
```

{% hint style="info" %}
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.
{% endhint %}

**Custom Identity Provider**

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

```bash
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"}'
```

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:

```bash
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
}'
```

**Provider creation response**

All provider creation requests return the Provider ID, which you will need to create and manage data sources:

```json
{
  "value": {
    "id": "a6ef8d8d-d17b-4491-a67a-635ad70f1ba9",
    "name": "GitHub",
    "custom_template": "application",
    "state": "ENABLED",
    "application_types": [],
    "resource_types": [],
    "idp_types": [],
    "schema_definition_json": "e30="
  }
}
```

**Provider creation fields**

| Field                                | Type    | Required | Description                                                                                                                                                     |
| ------------------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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`.                                                                                                   |
| `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.                                                               |

{% hint style="info" %}

* 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.
  {% endhint %}

**Using the Python SDK**

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

```python
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}
)
```

#### Create a Data Source for the Provider

Each provider needs at least one data source. Create one with [Create Custom Provider Datasource](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#create-custom-provider-datasource)

```bash
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"}'
```

The response will include the data source ID:

```json
{
  "value": {
    "id": "1bd31da0-64ee-4dfe-82c9-cb9f0f2fc369",
    "name": "DemoApp - Documentation Datasource"
  }
}
```

* 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 [Push Custom Provider Datasource](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#push-custom-provider-datasource). 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 `"`).

{% code title="body.json" %}

```json
{
  "id": "532f6fe3-189f-4576-afdf-8913088961e4",
  "compression_type": "none",
  "data_source_id": "b6a32af6-b854-47e1-8325-e5984f78bb4d",
  "json_data": "{\"name\":\"CustomApp\",\"application_type\"...}"
}
```

{% endcode %}

```bash
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
```

#### Get Custom Providers

```bash
curl -X GET "https://$VEZA_URL/api/v1/providers/custom" \
-H 'accept: application/json' \
-H 'authorization: Bearer '$API_KEY
```

#### Get Custom Data Sources

```bash
curl -X GET "https://$VEZA_URL/api/v1/providers/custom/$PROVIDER_ID" \
-H 'accept: application/json' \
-H 'authorization: Bearer '$API_KEY
```

#### Update Custom Data Source

Specifying the Provider ID and Data Source ID, perform the same [post operation](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#push-custom-provider-datasource) used for the initial push.

```bash
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
```

To update an existing data source, use the operations [List Provider](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#list-custom-providers) and [List Datasources](/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api/operations.md#list-custom-provider-datasources) operations to get the provider and data source IDs.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/oaa/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.