> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/management/provider-management.md).

# Provider Management API

Generic API for managing integrations of every type

The Provider Management API manages Veza integrations of every type through one set of generic endpoints. In the API, an integration is a provider resource.

Use these endpoints to:

* Create integrations of any supported type
* List integrations across all types, with filtering and pagination
* Get a single integration by ID
* Update common fields (`name`, `labels`, `owners`, `data_plane_id`) and type-specific settings in `vendor`
* Delete integrations

{% hint style="warning" %}
The per-type provider endpoints, such as `POST /api/v1/providers/aws` and `GET /api/v1/providers/okta`, are deprecated. Use the generic endpoints on this page instead. The deprecated endpoints remain available and continue to work. Veza plans to remove them on March 31, 2027. See [Deprecated per-type endpoints](#deprecated-per-type-endpoints).
{% endhint %}

Every request needs an [API token](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md). To create, update, or delete an integration, the token needs the `admin`, `provider_manager`, or `integration_owner` role. Each integration collects data through an Insight Point, set with `data_plane_id`; see [Choosing a data plane](#choosing-a-data-plane-insight-point). Before you create an integration, complete the setup in the source system that its [integration guide](/4yItIzMvkpAvMVFAamTf/integrations/integrations.md) describes.

## Deprecated per-type endpoints

The deprecation covers the per-type create, read, update, and delete endpoints under `/api/v1/providers/<type>`, such as `/api/v1/providers/aws` or `/api/v1/providers/okta`. Most integration types have them. Type-specific helper operations that share the same path prefix are unaffected, and keep working after the removal date. These are `GET /api/v1/providers/aws:trustpolicy`, `GET /api/v1/providers/aws/{id}:checkpolicy`, `GET /api/v1/providers/google_cloud/{id}:checkpolicy`, `GET /api/v1/providers/google_cloud:aws_role_arn`, `GET /api/v1/providers/salesforce:default_object_types`, `GET /api/v1/providers/salesforce_commerce_cloud:default_object_types`, and `POST /api/v1/providers/workday:worker_properties`. Endpoints under `/api/v1/providers` that are not tied to one integration type, such as `/api/v1/providers/types`, `/api/v1/providers/configuration-definitions`, and the [Data Sources API](/4yItIzMvkpAvMVFAamTf/developers/api/management/datasources.md) under `/api/v1/providers/datasources`, are also unaffected.

| Deprecated endpoint                    | Use instead                                                                                          |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `POST /api/v1/providers/<type>`        | [`POST /api/v1/providers`](#create-a-provider), with the type in `type` and its settings in `vendor` |
| `GET /api/v1/providers/<type>`         | [`GET /api/v1/providers`](#list-all-providers), with `filter=type eq "<TYPE>"`                       |
| `GET /api/v1/providers/<type>/{id}`    | [`GET /api/v1/providers/{id}`](#get-a-provider)                                                      |
| `PATCH /api/v1/providers/<type>/{id}`  | [`PATCH /api/v1/providers/{id}`](#update-provider-partial)                                           |
| `DELETE /api/v1/providers/<type>/{id}` | [`DELETE /api/v1/providers/{id}`](#delete-provider)                                                  |

Of the per-type endpoints, only the Workday update endpoint, `PUT /api/v1/providers/workday/{id}`, accepts `PUT`. Every other per-type update accepts `PATCH` only. The generic endpoint accepts both; see [Update Provider (Full)](#update-provider-full) and [Update Provider (Partial)](#update-provider-partial).

{% hint style="info" %}
The Open Authorization API endpoints under `/api/v1/providers/custom` are not affected by this deprecation. Custom providers are created and managed through the [Open Authorization API](/4yItIzMvkpAvMVFAamTf/developers/api/oaa.md).
{% endhint %}

## Create a Provider

Create an integration of any supported type with a single request.

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/v1/providers" method="post" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-52896198b0199515de31fd5ac6c2094ad6ea5bf1%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request body

Send the provider object directly as the request body; it is not wrapped in a `value` field. Common fields sit at the top level, and the type-specific configuration goes in the `vendor` object.

| Field               | Required | Description                                                                                                                                                                         |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`              | Yes      | Display name for the integration.                                                                                                                                                   |
| `type`              | Yes      | Provider type, such as `AWS` or `DATABRICKS`. Determines the expected contents of `vendor`.                                                                                         |
| `data_plane_id`     | Yes      | [Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) ID that collects data for this integration.                                                       |
| `vendor`            | Yes      | Type-specific configuration such as credentials, regions, and filters. Its fields depend on `type`.                                                                                 |
| `owners`            | No       | Veza user or group IDs to assign as owners.                                                                                                                                         |
| `labels`            | No       | Metadata labels, such as `production`.                                                                                                                                              |
| `secret_references` | No       | Array that points credential fields at a secret in an external vault, instead of sending them in `vendor`. See [Using an external secrets vault](#using-an-external-secrets-vault). |

{% hint style="info" %}
Enum values inside `vendor` are supplied by name. For example, AWS `credentials_type` accepts `STATIC`, `EC2_INSTANCE_PROFILE`, `ASSUME_CUSTOMER_ROLE`, or `ECS_TASK_ROLE`.
{% endhint %}

{% hint style="warning" %}
Veza ignores unrecognized fields inside `vendor` instead of rejecting them. A misspelled field name returns `200` with that setting silently dropped, so check the created integration's configuration if it does not behave as expected.
{% endhint %}

### Choosing a data plane (Insight Point)

`data_plane_id` selects the [Insight Point](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/insight-point.md) that collects data for the integration. Every Veza tenant has a built-in managed Insight Point, **(default) Veza Insight Point**, with the same ID in every tenant: `a2e32a80-9d64-4725-b4a9-8de6ffd0682b`. It runs inside the Veza control plane, so use it only for sources reachable from the public internet. On-premises and private-network sources need a self-hosted Insight Point that can reach them. To find a self-hosted Insight Point's ID, read the `data_plane_id` of an existing integration returned by [List All Providers](#list-all-providers), or check its configuration in the Veza UI.

Some options require a self-hosted Insight Point regardless of the source: the AWS `EC2_INSTANCE_PROFILE` and `ECS_TASK_ROLE` credential types (the Insight Point runs in the target AWS environment and supplies the role), and [external secrets vaults](#using-an-external-secrets-vault) (the Insight Point needs connectivity to the vault).

### Supported provider types

The generic endpoint accepts every integration type registered in your tenant, including Active Directory, Google Cloud, Okta, OneLogin, and Snowflake. A request for a type that is not registered returns a `provider type ... is not supported` error.

{% hint style="info" %}
The API is the source of truth for which types your tenant accepts. To read the list, see [List provider types](/4yItIzMvkpAvMVFAamTf/developers/api/management/providers/listprovidertypes.md).
{% endhint %}

The examples on this page show `vendor` payloads for a representative set of types. Every other registered type works the same way: the type goes in `type`, and its settings go in `vendor`. For the `vendor` field definitions of a specific type, see the object schemas in [Cloud Platforms and Data Providers](/4yItIzMvkpAvMVFAamTf/developers/api/management/providers.md), which covers AWS, Azure, Google Cloud, Snowflake, SQL Server, and Trino, or in [Identity Provider Integration APIs](/4yItIzMvkpAvMVFAamTf/developers/api/management/idp.md), which covers Active Directory, Okta, and OneLogin. For a type covered by neither, the field schema may be available from `GET /api/v1/providers/configuration-definitions/{provider_type}`. Not every type has one. That request returns `404` for a type without a definition, and `GET /api/v1/providers/configuration-definitions` lists the types that have one.

### Example: create an AWS integration

```bash
curl -X POST \
  "https://{tenant}.vezacloud.com/api/v1/providers" \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS Production",
    "type": "AWS",
    "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
    "vendor": {
      "credentials_type": "ASSUME_CUSTOMER_ROLE",
      "account_id": "123456789012",
      "assume_role_name": "VezaDiscoveryRole",
      "assume_role_external_id": "veza-external-id",
      "regions": ["us-east-1", "us-west-2"]
    },
    "labels": ["production"]
  }'
```

For static credentials, set `"credentials_type": "STATIC"` and provide `access_key_id` and `secret_key` instead of the assume-role fields.

### Vendor payloads by type

The `vendor` object for more types, shown as examples current as of publication. Combine one of these with the top-level `name`, `type`, and `data_plane_id` fields shown above.

{% tabs %}
{% tab title="Azure" %}

```json
{
  "tenant_id": "12345678-1234-1234-1234-123456789012",
  "client_id": "87654321-4321-4321-4321-210987654321",
  "client_secret": "your-client-secret",
  "services": ["SHAREPOINT", "AZURE_SQL_SERVER"]
}
```

{% endtab %}

{% tab title="Databricks" %}

```json
{
  "host": "https://dbc-a1b2c3d4-e5f6.cloud.databricks.com",
  "authentication_method": "PAT",
  "token": "dapiXXXXXXXXXXXXXXXXXXXXXXXX",
  "cluster_http_endpoint": "/sql/1.0/warehouses/abcd1234efgh5678"
}
```

{% endtab %}

{% tab title="Oracle Cloud" %}

```json
{
  "user_ocid": "ocid1.user.oc1..aaaaexampleuser",
  "tenancy_ocid": "ocid1.tenancy.oc1..aaaaexampletenancy",
  "fingerprint": "12:34:56:78:90:ab:cd:ef:12:34:56:78:90:ab:cd:ef",
  "region": "us-ashburn-1",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}
```

{% endtab %}

{% tab title="SQL Server" %}

```json
{
  "host": "sqlserver.company.com",
  "port": 1433,
  "username": "veza_user",
  "password": "your-password",
  "database_allow_list": ["ProductionDB", "AnalyticsDB"]
}
```

{% endtab %}

{% tab title="Trino" %}

```json
{
  "host": "trino.company.com",
  "port": 8080,
  "username": "veza_user",
  "password": "your-password",
  "aws_s3_object_config": {
    "credentials_type": "STATIC",
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "your-secret-key",
    "region": "us-east-1",
    "bucket": "trino-metadata-bucket",
    "object": "cluster-metadata.json"
  }
}
```

Trino requires `aws_s3_object_config`. Its `credentials_type` must be `STATIC`, `ASSUME_CUSTOMER_ROLE`, or `EC2_INSTANCE_PROFILE`. Note that `ECS_TASK_ROLE` is not accepted here, unlike top-level AWS. `ASSUME_CUSTOMER_ROLE` replaces the access keys with `account_id`, `assume_role_name`, and `assume_role_external_id`. `EC2_INSTANCE_PROFILE` needs only `region`, `bucket`, and `object`.
{% endtab %}
{% endtabs %}

### Authentication methods

Several types support more than one authentication method. Set the `vendor` fields for the method you use:

| Type             | Methods (`vendor` fields)                                                                                                                                                                                                                                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AWS              | `credentials_type`: `ASSUME_CUSTOMER_ROLE` (`assume_role_name`, `assume_role_external_id`), `STATIC` (`access_key_id`, `secret_key`), or `EC2_INSTANCE_PROFILE` / `ECS_TASK_ROLE` (no stored keys; requires a self-hosted Insight Point running in the target AWS environment).                                              |
| Azure            | Client secret (`client_secret`) or certificate (`auth_certificate`, `auth_certificate_password`).                                                                                                                                                                                                                            |
| Databricks       | `authentication_method`: `PAT` (`token`) or `EXTERNAL_OAUTH` (the `external_oauth_*` fields).                                                                                                                                                                                                                                |
| Snowflake        | `authentication_method`: `BASIC` (`password`), `KEY_PAIR` (`private_key`, `private_key_password`), `EXTERNAL_OAUTH`, or `EXTERNAL_OAUTH_CLIENT_CREDENTIALS` (`external_oauth_token_endpoint`, `external_oauth_client_id`, `external_oauth_client_secret`, `external_oauth_audience`, and optionally `external_oauth_scope`). |
| Okta             | `credentials_type`: `API_TOKEN` (`token`) or `OAUTH` (`client_id`, `private_key_id`, `private_key`).                                                                                                                                                                                                                         |
| Active Directory | `username` and `password`; set `kerberos_auth: true` for Kerberos over TLS, or both `kerberos_auth: true` and `kerberos_auth_mode_token: true` for token-cache authentication (no stored credentials).                                                                                                                       |

Oracle Cloud authenticates with an API signing key (`user_ocid`, `tenancy_ocid`, `fingerprint`, `private_key`). Trino authenticates with `username` and `password`. SQL Server authenticates with `username` and `password`, or with Kerberos: set `kerberos_auth: true` and `kerberos_realm`, and provide either `password` or a base64-encoded `kerberos_keytab`. See [SQL Server Kerberos authentication](/4yItIzMvkpAvMVFAamTf/integrations/integrations/sql-server.md#kerberos-authentication).

### Using an external secrets vault

Instead of sending credentials in `vendor`, you can add a top-level `secret_references` array that points the integration's credential fields at a secret in an external vault. When Secrets Vaults is enabled for your tenant, you can then omit those fields from `vendor`, even when they are otherwise required. Of the types on this page, AWS, Azure, Active Directory, Google Cloud, and Okta have fields that can come from a vault. AWS and Google Cloud need Insight Point v2026.11.2 or later. Secrets Vaults is an Early Access feature and needs a self-hosted Insight Point that can reach the vault. For the reference format, the eligible fields for each integration, and the complete workflow, see [Using secret references via API](/4yItIzMvkpAvMVFAamTf/integrations/connectivity/secrets-vaults/secret-references-api.md).

### More example payloads

These examples show complete request bodies, including the top-level fields, for five more types.

{% tabs %}
{% tab title="Google Cloud" %}

```json
{
  "name": "GCP Production",
  "type": "GOOGLE_CLOUD",
  "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
  "vendor": {
    "credentials_json": "{ service account key JSON }",
    "workspace_email": "service-account@project.iam.gserviceaccount.com",
    "customer_id": "C01234567",
    "project_allow_list": ["prod-project-1", "prod-project-2"],
    "services": ["IAM", "STORAGE", "COMPUTE", "WORKSPACE", "BIGQUERY"]
  }
}
```

{% endtab %}

{% tab title="Okta" %}

```json
{
  "name": "Okta Production",
  "type": "OKTA",
  "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
  "vendor": {
    "domain": "your-org.okta.com",
    "credentials_type": "API_TOKEN",
    "token": "00XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}
```

{% endtab %}

{% tab title="OneLogin" %}

```json
{
  "name": "OneLogin Production",
  "type": "ONE_LOGIN",
  "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
  "vendor": {
    "domain": "your-org.onelogin.com",
    "region": "us",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }
}
```

{% endtab %}

{% tab title="Snowflake" %}

```json
{
  "name": "Snowflake Production",
  "type": "SNOWFLAKE",
  "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
  "vendor": {
    "account_locator": "xy12345",
    "region": "us-east-1",
    "cloud": "aws",
    "user": "veza_user",
    "authentication_method": "BASIC",
    "password": "your-password",
    "role": "VEZA_ROLE",
    "warehouse": "COMPUTE_WH"
  }
}
```

{% endtab %}

{% tab title="Active Directory" %}

```json
{
  "name": "AD Production",
  "type": "ACTIVE_DIRECTORY",
  "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
  "vendor": {
    "host": "dc1.corp.example.com",
    "ad_fqdn": "corp.example.com",
    "port": 636,
    "username": "veza-service",
    "password": "your-password",
    "ldaps_certificate": "<base64-encoded PEM certificate>",
    "domains": ["corp.example.com"]
  }
}
```

`host`, `domains`, and `ad_fqdn` are always required. `username`, `password`, and `ldaps_certificate` are also required, with two exceptions:

* **Kerberos token authentication**: set both `kerberos_auth: true` and `kerberos_auth_mode_token: true` to waive all three. Setting `kerberos_auth: true` on its own selects Kerberos with TLS, which still requires them.
* **External secrets vault**: when the integration has `secret_references` and Secrets Vaults is enabled for your tenant, you can omit all three from `vendor` and store them in the vault secret instead. See [Using an external secrets vault](#using-an-external-secrets-vault).

`ldaps_certificate` must be base64-encoded when you send it inline, `host` must be a fully qualified name or an IP address, and `domains` accepts one entry.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The `type` value is always the uppercase enum name, which is not always the deprecated endpoint's path segment in uppercase. Three types differ: send `ACTIVE_DIRECTORY` for `activedirectory`, `ONE_LOGIN` for `onelogin`, and `SQL_SERVER` for `sqlserver`. For every other type, the enum name is the path segment uppercased.
{% endhint %}

## List All Providers

Returns a list of all configured integrations across all types. Supports filtering and pagination.

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/v1/providers" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-52896198b0199515de31fd5ac6c2094ad6ea5bf1%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Query Parameters

| Parameter                   | Type    | Description                                                                                       |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `page_size`                 | integer | Maximum number of results per page (default: 100, maximum: 1000)                                  |
| `page_token`                | string  | Token for retrieving the next page of results                                                     |
| `filter`                    | string  | Filter expression, for example `state eq "ENABLED"` or `type eq "AWS"`. Values are double-quoted. |
| `include_datasource_status` | string  | Include datasource status in response                                                             |
| `include_type_summary`      | boolean | Include type summary field                                                                        |

### Example Request

```bash
curl -sS -G "https://{tenant}.vezacloud.com/api/v1/providers" \
  --data-urlencode 'page_size=10' \
  --data-urlencode 'filter=state eq "ENABLED"' \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Accept: application/json"
```

`curl -G --data-urlencode` handles the encoding of the quoted values. Combine conditions with `and`, for example `filter=type eq "AWS" and state eq "ENABLED"`.

Veza matches filter values for `type`, `state`, and `status` case-sensitively against the enum name, so `type eq "AWS"` matches and `type eq "aws"` returns a `400`. Of the filterable fields, only `name` ignores case. `filter` has no `id` operator; to read one integration by ID, use [Get a Provider](#get-a-provider). The list response omits `secret_references`.

### Example Response

```json
{
  "values": [
    {
      "id": "883dd869-8762-4187-8767-1c387de14b4b",
      "vendor_id": "123456789012",
      "name": "AWS-Production",
      "type": "AWS",
      "state": "ENABLED",
      "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
      "status": "SUCCESS",
      "external_id": "123456789012",
      "team_id": "team-uuid-here",
      "team_name": "Platform Team",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-08-26T14:22:00Z",
      "created_by": "user-uuid",
      "updated_by": "user-uuid",
      "owners": ["user-uuid-1", "group-uuid-1"],
      "labels": ["production", "critical"],
      "vendor": {
        "account_id": "123456789012",
        "credentials_type": "ASSUME_CUSTOMER_ROLE",
        "assume_role_name": "veza-discovery-ro",
        "regions": ["us-east-1"],
        "services": ["AWS_IAM", "EC2", "S3"]
      },
      "lifecycle_management_state": "NOT_CONFIGURED",
      "provisioning": false
    },
    {
      "id": "fa04e92f-6e0d-4285-ba58-86a20c6941ff",
      "vendor_id": "12345678-1234-1234-1234-123456789012",
      "name": "Azure-Production",
      "type": "AZURE",
      "state": "ENABLED",
      "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
      "status": "SUCCESS",
      "external_id": "12345678-1234-1234-1234-123456789012",
      "team_id": "team-uuid-here",
      "team_name": "Platform Team",
      "created_at": "2024-02-01T09:15:00Z",
      "updated_at": "2024-08-26T13:45:00Z",
      "owners": [],
      "labels": ["production"],
      "vendor": {
        "tenant_id": "12345678-1234-1234-1234-123456789012",
        "client_id": "87654321-4321-4321-4321-210987654321",
        "services": ["SHAREPOINT", "AZURE_SQL_SERVER"]
      },
      "lifecycle_management_state": "NOT_CONFIGURED",
      "provisioning": false
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOjEwfQ=="
}
```

{% hint style="info" %}
Use `page_size` and `page_token` parameters for pagination. Continue fetching pages until `next_page_token` is empty or absent.
{% endhint %}

## Get a Provider

**Available in Veza v2026.10.12 and later.**

Returns one integration of any type by its ID. The response wraps the provider in a `value` field and includes the same fields as a list entry. It also includes `secret_references` when the integration has any. `vendor` omits encrypted fields, such as passwords, tokens, and private keys.

`GET /api/v1/providers/{id}`

### Query Parameters

| Parameter                                 | Type    | Description                                     |
| ----------------------------------------- | ------- | ----------------------------------------------- |
| `include_created_by_and_updated_by_names` | boolean | Include `created_by_name` and `updated_by_name` |
| `include_type_summary`                    | boolean | Include type summary field                      |

### Example Request

```bash
curl -X GET \
  "https://{tenant}.vezacloud.com/api/v1/providers/883dd869-8762-4187-8767-1c387de14b4b" \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Accept: application/json"
```

### Example Response

```json
{
  "value": {
    "id": "883dd869-8762-4187-8767-1c387de14b4b",
    "vendor_id": "123456789012",
    "name": "AWS-Production",
    "type": "AWS",
    "state": "ENABLED",
    "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
    "status": "SUCCESS",
    "external_id": "123456789012",
    "team_id": "team-uuid-here",
    "team_name": "Platform Team",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-08-26T14:22:00Z",
    "created_by": "user-uuid",
    "updated_by": "user-uuid",
    "owners": ["user-uuid-1", "group-uuid-1"],
    "labels": ["production", "critical"],
    "vendor": {
      "account_id": "123456789012",
      "credentials_type": "ASSUME_CUSTOMER_ROLE",
      "assume_role_name": "veza-discovery-ro",
      "regions": ["us-east-1"],
      "services": ["AWS_IAM", "EC2", "S3"]
    },
    "lifecycle_management_state": "NOT_CONFIGURED",
    "provisioning": false
  }
}
```

An ID that matches no integration returns `404`.

## Update Provider (Full)

Update a provider with `PUT`. Send the provider object directly as the request body, not wrapped in a `value` field. `PUT` does not infer which fields to change, so list them in an `update_mask` query parameter; fields omitted from the mask stay unchanged. Omitting `update_mask` returns `400` with the message `update_mask: Must be set`. Prefer [Update Provider (Partial)](#update-provider-partial), which derives the mask from the request body.

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/v1/providers/{value.id}" method="put" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-52896198b0199515de31fd5ac6c2094ad6ea5bf1%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Example Request

```bash
curl -X PUT \
  "https://{tenant}.vezacloud.com/api/v1/providers/883dd869-8762-4187-8767-1c387de14b4b?update_mask=name,data_plane_id,owners,labels" \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "883dd869-8762-4187-8767-1c387de14b4b",
    "name": "AWS-Production-Updated",
    "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
    "owners": ["user-uuid-1", "group-uuid-1"],
    "labels": ["production", "critical", "pci"]
  }'
```

### Example Response

```json
{
  "value": {
    "id": "883dd869-8762-4187-8767-1c387de14b4b",
    "vendor_id": "123456789012",
    "name": "AWS-Production-Updated",
    "type": "AWS",
    "state": "ENABLED",
    "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
    "status": "PENDING",
    "external_id": "123456789012",
    "team_id": "team-uuid-here",
    "team_name": "Platform Team",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-08-26T15:30:00Z",
    "created_by": "user-uuid",
    "updated_by": "user-uuid",
    "owners": ["user-uuid-1", "group-uuid-1"],
    "labels": ["production", "critical", "pci"],
    "vendor": {
      "account_id": "123456789012",
      "credentials_type": "ASSUME_CUSTOMER_ROLE",
      "assume_role_name": "veza-discovery-ro",
      "regions": ["us-east-1"],
      "services": ["AWS_IAM", "EC2", "S3"]
    },
    "lifecycle_management_state": "NOT_CONFIGURED",
    "provisioning": false
  }
}
```

## Update Provider (Partial)

Update selected fields with `PATCH`. Send the provider object directly as the request body, not wrapped in a `value` field, and include only the fields you want to change. `PATCH` infers the `update_mask` from the fields present in the body, so you do not need to send one. To override that inference, pass an explicit `update_mask` query parameter.

Changing a type-specific setting works the same way: send the changed field inside `vendor`, for example `{"vendor": {"assume_role_name": "veza-discovery-ro"}}`. Veza merges it into the integration's stored configuration, so the settings you omit keep their current values.

{% hint style="warning" %}
A list inside `vendor` is replaced, not merged, so read the current list first and send the full list you want. For AWS `services`, dropping a service also deletes the data Veza collected for it. See [Disable AWS services](/4yItIzMvkpAvMVFAamTf/developers/api/management/disable-aws-services.md).
{% endhint %}

{% hint style="info" %}
Unlike [Create a Provider](#create-a-provider), which silently ignores a `vendor` field it does not recognize, `PATCH` rejects one: a misspelled field returns `400` with `unknown vendor field`.
{% endhint %}

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/v1/providers/{value.id}" method="patch" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-52896198b0199515de31fd5ac6c2094ad6ea5bf1%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Example Request

```bash
curl -X PATCH \
  "https://{tenant}.vezacloud.com/api/v1/providers/883dd869-8762-4187-8767-1c387de14b4b" \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "883dd869-8762-4187-8767-1c387de14b4b",
    "name": "AWS-Production-Renamed",
    "labels": ["production", "updated"]
  }'
```

### Example Response

```json
{
  "value": {
    "id": "883dd869-8762-4187-8767-1c387de14b4b",
    "vendor_id": "123456789012",
    "name": "AWS-Production-Renamed",
    "type": "AWS",
    "state": "ENABLED",
    "data_plane_id": "a2e32a80-9d64-4725-b4a9-8de6ffd0682b",
    "status": "PENDING",
    "external_id": "123456789012",
    "team_id": "team-uuid-here",
    "team_name": "Platform Team",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-08-26T15:45:00Z",
    "owners": ["user-uuid-1", "group-uuid-1"],
    "labels": ["production", "updated"],
    "vendor": {
      "account_id": "123456789012",
      "credentials_type": "ASSUME_CUSTOMER_ROLE",
      "assume_role_name": "veza-discovery-ro",
      "regions": ["us-east-1"],
      "services": ["AWS_IAM", "EC2", "S3"]
    },
    "lifecycle_management_state": "NOT_CONFIGURED",
    "provisioning": false
  }
}
```

## Delete Provider

Delete an integration by ID.

{% hint style="warning" %}
Deletion is permanent. It removes the integration and all of its data sources.
{% endhint %}

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/v1/providers/{id}" method="delete" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-52896198b0199515de31fd5ac6c2094ad6ea5bf1%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Example Request

```bash
curl -X DELETE \
  "https://{tenant}.vezacloud.com/api/v1/providers/883dd869-8762-4187-8767-1c387de14b4b" \
  -H "Authorization: Bearer {your_api_key}"
```

### Example Response

Returns an empty response with HTTP status `200 OK` on success.

```json
{}
```

## Provider Response Fields

### Core Fields

| Field           | Type   | Behavior    | Description                                                         |
| --------------- | ------ | ----------- | ------------------------------------------------------------------- |
| `id`            | string | Output-only | Unique provider identifier (UUID)                                   |
| `vendor_id`     | string | Output-only | Provider-specific identifier, for example the AWS account ID        |
| `name`          | string | Mutable     | Display name for the provider                                       |
| `type`          | string | Immutable   | Provider type, such as `AWS`, `AZURE`, or `GOOGLE_CLOUD`            |
| `state`         | enum   | Output-only | Provider state: `ENABLED`, `DISABLED`, `DELETING`, `PENDING_DELETE` |
| `status`        | enum   | Output-only | Discovery status: `PENDING`, `SUCCESS`, `ERROR`, `UNAUTHENTICATED`  |
| `data_plane_id` | string | Mutable     | Insight Point ID for data collection                                |
| `external_id`   | string | Output-only | External identifier for cross-system references                     |

### Metadata Fields

| Field             | Type      | Behavior    | Description                                    |
| ----------------- | --------- | ----------- | ---------------------------------------------- |
| `created_at`      | timestamp | Output-only | Creation timestamp                             |
| `updated_at`      | timestamp | Output-only | Last modification timestamp                    |
| `created_by`      | string    | Output-only | User ID who created the provider               |
| `updated_by`      | string    | Output-only | User ID who last modified the provider         |
| `created_by_name` | string    | Output-only | Display name of creator (when requested)       |
| `updated_by_name` | string    | Output-only | Display name of last modifier (when requested) |

### Organization Fields

| Field         | Type           | Behavior    | Description                                           |
| ------------- | -------------- | ----------- | ----------------------------------------------------- |
| `team_id`     | string         | Output-only | Owning team identifier                                |
| `team_name`   | string         | Output-only | Owning team display name                              |
| `owners`      | array\[string] | Mutable     | List of Veza user or group IDs with owner permissions |
| `owner_names` | array\[string] | Output-only | Display names of owners                               |
| `labels`      | array\[string] | Mutable     | Metadata labels, such as `production` or `pci`        |
| `rbac_id`     | string         | Output-only | RBAC identifier for access control                    |

### Status Fields

| Field                           | Type    | Behavior    | Description                                |
| ------------------------------- | ------- | ----------- | ------------------------------------------ |
| `extractors_datasource_status`  | enum    | Output-only | Aggregate status of extractor datasources  |
| `discoverers_datasource_status` | enum    | Output-only | Aggregate status of discoverer datasources |
| `lifecycle_management_state`    | object  | Output-only | Lifecycle Management provisioning state    |
| `provisioning`                  | boolean | Mutable     | Whether Lifecycle Management is enabled    |

### Vendor Configuration

| Field    | Type   | Behavior | Description                                                                                                                                                                                                                                                                                                                                                                               |
| -------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vendor` | object | Mutable  | Type-specific configuration (credentials, regions, filters). Its fields depend on `type`. Set it when [creating a provider](#create-a-provider) and change it with [Update Provider (Partial)](#update-provider-partial). Get and list responses return it populated, minus encrypted fields such as passwords, tokens, and private keys, which are stored separately and never returned. |

## Error Responses

All endpoints return standard HTTP status codes:

| Status Code | Description                                                                                                                             |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | Success                                                                                                                                 |
| 400         | Bad Request - Invalid parameters or request body, or an update to an integration that is being deleted (`PENDING_DELETE` or `DELETING`) |
| 401         | Unauthorized - Invalid or missing API key                                                                                               |
| 403         | Forbidden - Insufficient permissions, or the integration type is not licensed for your tenant (`Provider type is not licensed.`)        |
| 404         | Not Found - Provider does not exist                                                                                                     |
| 409         | Conflict - Provider already exists or state conflict                                                                                    |
| 422         | Unprocessable Entity - Validation error                                                                                                 |
| 500         | Internal Server Error                                                                                                                   |

## Related Documentation

* [Cloud Platforms and Data Providers](/4yItIzMvkpAvMVFAamTf/developers/api/management/providers.md)
* [Data Sources API](/4yItIzMvkpAvMVFAamTf/developers/api/management/datasources.md)
* [API Authentication](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/management/provider-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.