# Configure a Databricks Unity Catalog Integration

{% @mermaid/diagram content="graph LR
A(Authenticate) --> B(Configure integration) --> C(Map users and create policies) --> D(Register metadata);
style A fill:#fff
style B fill:#2F6BA7,color:#fff
style C fill:#fff
style D fill:#fff" %}

Immuta’s integration with Unity Catalog allows you to manage multiple Databricks workspaces through Unity Catalog while protecting your data with Immuta policies. Instead of manually creating UDFs or granting access to each table in Databricks, you can author your policies in Immuta and have Immuta manage and enforce Unity Catalog access-control policies on your data in Databricks clusters or SQL warehouses.

Use the `/integrations` endpoint to

* [configure a Databricks Unity Catalog integration](#configure-the-integration)
* [get a Databricks Unity Catalog integration](#get-an-integration)
* [get all integrations](#get-all-integrations)
* [update a Databricks Unity Catalog integration](#update-an-integration-configuration)
* [delete a Databricks Unity Catalog integration](#delete-an-integration)

## Requirements

### Permissions

* `APPLICATION_ADMIN` Immuta permission
* The Databricks user [running the installation script](#user-content-fn-1)[^1] must have the following privileges:
  * Account admin
  * `CREATE CATALOG` privilege on the Unity Catalog metastore to create an Immuta-owned catalog and tables
  * [Metastore admin](#user-content-fn-2)[^2] (only required if enabling query audit)

See the [Databricks documentation](https://docs.databricks.com/en/data-governance/unity-catalog/manage-privileges/privileges.html) for more details about Unity Catalog privileges and securable objects.

### Authentication

* **Access token authentication**: If using this method, generate a personal access token for the service principal that Immuta will use to manage policies in Unity Catalog. This service principal must have the [privileges listed above](#permissions) for the metastore associated with the Databricks workspace.
* **OAuth machine-to-machine (M2M) authentication**: If using this method, follow [Databricks documentation to create a client secret](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m.html) for the Immuta service principal. This service principal must have the [privileges listed above](#permissions) for the metastore associated with the Databricks workspace.

## Configure the integration

1. In Databricks, [create a service principal](https://docs.databricks.com/en/admin/users-groups/service-principals.html#manage-service-principals-in-your-account) with the privileges below. Immuta uses this service principal continuously to orchestrate Unity Catalog policies and maintain state between Immuta and Databricks.
   1. `USE CATALOG` and `MANAGE` on all catalogs containing securables registered as Immuta data sources and `USE SCHEMA` on all schemas containing securables registered as Immuta data sources.
   2. `MODIFY` and `SELECT` on all securables registered as Immuta data sources. `MANAGE` and `MODIFY` are required so that the service principal can apply row filters and column masks on the securable; to do so, the service principal must also have `SELECT` on the securable as well as `USE CATALOG` on its parent catalog and `USE SCHEMA` on its parent schema. Since privileges are inherited, you can grant the service principal the `MODIFY` and `SELECT` privilege on all catalogs or schemas containing Immuta data sources, which automatically grants the service principal the `MODIFY` and `SELECT` privilege on all current and future securables in the catalog or schema. The service principal also inherits `MANAGE` from the parent catalog for the purpose of applying row filters and column masks, but that privilege must be set directly on the parent catalog in order for grants to be fully applied.
2. Opt to enable query audit for Unity Catalog:
   1. If you will configure the integration using the manual setup option, the Immuta script you will generate includes the SQL statements for granting required privileges to the service principal, so you can skip this step and continue to the manual setup section.
   2. If you will configure the integration using the automatic setup option, [manually grant the Immuta service principal access to the Databricks Unity Catalog system tables](https://docs.databricks.com/en/administration-guide/system-tables/index.html#grant-access-to-system-tables). For Databricks Unity Catalog audit to work, the service principal must have the following access at minimum:
      * `USE CATALOG` on the `system` catalog
      * `USE SCHEMA` on the `system.access` and `system.query` schemas
      * `SELECT` on the following system tables:

        * `system.access.table_lineage`
        * `system.access.column_lineage`
        * `system.access.audit`
        * `system.query.history`

        Access to system tables is governed by Unity Catalog. No user has access to these system schemas by default. To grant access, a user that is both a metastore admin and an account admin must grant `USE_SCHEMA` and `SELECT` permissions on the system schemas to the service principal. See [Manage privileges in Unity Catalog](https://docs.databricks.com/en/data-governance/unity-catalog/manage-privileges/index.html) for more details.
3. You have two options for configuring your Databricks Unity Catalog integration. Select the method you prefer below to navigate to configuration instructions:
   * [**Automatic setup**](#automatic-setup): Immuta creates the catalogs, schemas, tables, and functions using the service principal you created.
   * [**Manual setup**](#manual-setup): Run the Immuta script in Databricks yourself to create the catalog. You can also modify the script to customize your storage location for tables, schemas, or catalogs. The user running the script must have the [Databricks privileges listed above](#permissions).

### Automatic setup

**Required permissions:** When performing an automatic setup, the credentials provided must have the [permissions listed above](#permissions).

Copy the request example, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML.

See the [**config** object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-configuration-objects) for parameter definitions, value types, and additional configuration options.

{% tabs %}
{% tab title="Access token authentication example" %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": true,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "token",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **token** is the Databricks personal access token. This is the access token for the Immuta service principal.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}
{% endtab %}

{% tab title="OAuth machine-to-machine authentication example" %}

```bash
curl -X 'POST' \
   'https://www.organization.immuta.com/integrations' \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
   -d '{
   "type": "Databricks",
   "autoBootstrap": true,
   "config": {
     "workspaceUrl": "www.example-workspace.cloud.databricks.com",
     "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
     "authenticationType": "oAuthM2M",
     "oAuthClientConfig": {
       "clientId": "123456abc",
       "clientSecret": "secret",
       "authorityUrl": "example.authority.com"
     },
     "catalog": "immuta"
   }
   }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **oAuthClientConfig** specifies your client ID, client secret, and authority URL. See the [object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-oauth-configuration-object) for details about child parameters.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}
{% endtab %}

{% tab title="Additional workspace connections" %}
{% hint style="warning" %}
To use this feature, you should first [set up a workspace-catalog binding in your Databricks account](https://docs.databricks.com/en/catalogs/binding.html#bind-a-catalog-to-one-or-more-workspaces).
{% endhint %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": true,
    "config": {
     "workspaceUrl": "www.example-workspace.cloud.databricks.com",
     "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
     "authenticationType": "oAuthM2M",
     "oAuthClientConfig": {
       "clientId": "<CLIENT ID>",
       "clientSecret": "<SECRET>",
       "authorityUrl": "https://oauth-provider.com/token",
       "useCertificate": false,
       "clientSecret": "<SECRET>"
       "scope": "all-apis"
      },
      "catalog": "immuta",
      "additionalWorkspaceConnections": [
      {
        "workspaceUrl": "workspace-b.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/2222222222222222",
        "authenticationType": "oAuthM2M",
        "oAuthClientConfig": {
          "clientId": "<CLIENT ID>",
          "authorityUrl": "https://oauth-provider.com/token",
          "useCertificate": false,
          "clientSecret": "<SECRET>"
          "scope": "all-apis"
        },
        "catalogs": ["isolated_catalog1"]
      },
      {
        "workspaceUrl": "workspace-c.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/3333333333333333",
        "authenticationType": "token",
        "oAuthClientConfig": {
          "clientId": "<CLIENT ID>",
          "authorityUrl": "https://oauth-provider.com/token",
          "useCertificate": true,
          "publicCertificateThumbprint": "<THUMBPRINT>",
          "oauthPrivateKey": "<PRIVATE KEY CONTENTS>",
          "scope": "all-apis"
        },
        "catalogs": ["isolated_catalog2", "isolated_catalog3"]
      }
    ]
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **oAuthClientConfig** specifies your client ID, client secret, and authority URL. See the [object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-oauth-configuration-object) for details about child parameters.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.
   * additionalWorkspaceConnections.**workspaceURL:** The Databricks workspace URL.
   * additionalWorkspaceConnections.**HTTPpath:** The HTTP path of the compute for the workspace.
   * additionalWorkspaceConnections.**authenticationType**: Specifies the authentication type to use to access the workspace. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace. See the [additionalWorkspaceConnections section](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#additional-workspace-connections) for details about additional authentication types and required and child attributes.
   * additionalWorkspaceConnections.**catalogs:** The catalog[^3] to use for the additional workspace connection.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}

{% hint style="warning" %}
If the integration tries to process an object that is in a bound catalog and none of the specified *additional workspaces* have access to that catalog, the operation will fail and an error will be reported.
{% endhint %}
{% endtab %}
{% endtabs %}

#### Response

The response returns the status of the Databricks Unity Catalog integration configuration connection. See the [response schema reference](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/reference-guides/response-schema) for details about the response schema.

{% tabs %}
{% tab title="200 response" %}
A successful response includes the validation tests statuses.

```json
{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "Metastore validation",
        "status": "passed"
      },
      {
        "name": "Basic Connection Test",
        "result": [
          {
            "1": 1
          }
        ],
        "status": "passed"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="Unsuccessful request" %}
An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/status-codes#post-errors) for a list of statuses, error messages, and troubleshooting guidance.

```json
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Databricks Unity Catalog integration already exists on www.example-workspace.cloud.databricks.com (id = 123456789)"
}
```

{% endtab %}
{% endtabs %}

### Manual setup

**Required permissions:** When performing a manual setup, the Databricks user running the script must have the [permissions listed above](#permissions).

To manually configure the integration, complete the following steps:

1. [Generate the Immuta script and run it in your Databricks environment.](#generate-the-script)
2. [Configure the integration in Immuta.](#configure-the-integration-in-immuta)

#### Generate the script

Copy the request example, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML.

See the [**config** object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-configuration-objects) for parameter definitions, value types, and additional configuration options.

{% tabs %}
{% tab title="Access token authentication example" %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": false,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "token",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **token** is the Databricks personal access token. This is the access token for the Immuta service principal.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.
3. Run the script returned in the response in your Databricks environment.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}
{% endtab %}

{% tab title="OAuth machine-to-machine authentication example" %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": false,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "oAuthM2M",
      "oAuthClientConfig": {
        "clientId": "123456abc",
        "clientSecret": "secret",
        "authorityUrl": "example.authority.com"
      },
      "catalog": "immuta"
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **oAuthClientConfig** specifies your client ID, client secret, and authority URL. See the [object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-oauth-configuration-object) for details about child parameters.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.
3. Run the script returned in the response in your Databricks environment.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}
{% endtab %}

{% tab title="Additional workspace connections" %}
{% hint style="warning" %}
To use this feature, you should first [set up a workspace-catalog binding in your Databricks account](https://docs.databricks.com/en/catalogs/binding.html#bind-a-catalog-to-one-or-more-workspaces).
{% endhint %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/scripts/create' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": false,
    "config": {
     "workspaceUrl": "www.example-workspace.cloud.databricks.com",
     "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
     "authenticationType": "oAuthM2M",
     "oAuthClientConfig": {
       "clientId": "<CLIENT ID>",
       "clientSecret": "<SECRET>",
       "authorityUrl": "https://oauth-provider.com/token",
       "useCertificate": false,
       "clientSecret": "<SECRET>"
       "scope": "all-apis"
      },
      "catalog": "immuta",
      "additionalWorkspaceConnections": [
      {
        "workspaceUrl": "workspace-b.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/2222222222222222",
        "authenticationType": "oAuthM2M",
        "oAuthClientConfig": {
          "clientId": "<CLIENT ID>",
          "authorityUrl": "https://oauth-provider.com/token",
          "useCertificate": false,
          "clientSecret": "<SECRET>"
          "scope": "all-apis"
        },
        "catalogs": ["isolated_catalog1"]
      },
      {
        "workspaceUrl": "workspace-c.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/3333333333333333",
        "authenticationType": "token",
        "oAuthClientConfig": {
          "clientId": "<CLIENT ID>",
          "authorityUrl": "https://oauth-provider.com/token",
          "useCertificate": true,
          "publicCertificateThumbprint": "<THUMBPRINT>",
          "oauthPrivateKey": "<PRIVATE KEY CONTENTS>",
          "scope": "all-apis"
        },
        "catalogs": ["isolated_catalog2", "isolated_catalog3"]
      }
    ]
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **oAuthClientConfig** specifies your client ID, client secret, and authority URL. See the [object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-oauth-configuration-object) for details about child parameters.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.
   * additionalWorkspaceConnections.**workspaceURL:** The Databricks workspace URL.
   * additionalWorkspaceConnections.**HTTPpath:** The HTTP path of the compute for the workspace.
   * additionalWorkspaceConnections.**authenticationType**: Specifies the authentication type to use to access the workspace. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace. See the [additionalWorkspaceConnections section](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#additional-workspace-connections) for details about additional authentication types and required and child attributes.
   * additionalWorkspaceConnections.**catalogs:** The catalog[^3] to use for the additional workspace connection.
3. Run the script returned in the response in your Databricks environment.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}

{% hint style="warning" %}
If the integration tries to process an object that is in a bound catalog and none of the specified *additional workspaces* have access to that catalog, the operation will fail and an error will be reported.
{% endhint %}
{% endtab %}
{% endtabs %}

**Response**

The response returns the script for you to run in your environment.

#### Configure the integration in Immuta

Copy the request example, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when [generating the script](#generate-the-script).

See the [**config** object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-configuration-objects) for parameter definitions, value types, and additional configuration options.

{% tabs %}
{% tab title="Access token authentication example" %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": false,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "token",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Pass the same payload you sent when [generating the script](#generate-the-script), where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **token** is the Databricks personal access token. This is the access token for the Immuta service principal.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}
{% endtab %}

{% tab title="OAuth machine-to-machine authentication example" %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": false,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "oAuthM2M",
      "oAuthClientConfig": {
        "clientId": "123456abc",
        "clientSecret": "secret",
        "authorityUrl": "example.authority.com"
      },
      "catalog": "immuta"
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Pass the same payload you sent when [generating the script](#generate-the-script), where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **oAuthClientConfig** specifies your client ID, client secret, and authority URL. See the [object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-oauth-configuration-object) for details about child parameters.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}
{% endtab %}

{% tab title="Additional workspace connections" %}
{% hint style="warning" %}
To use this feature, you should first [set up a workspace-catalog binding in your Databricks account](https://docs.databricks.com/en/catalogs/binding.html#bind-a-catalog-to-one-or-more-workspaces).
{% endhint %}

```bash
curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": false,
    "config": {
     "workspaceUrl": "www.example-workspace.cloud.databricks.com",
     "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
     "authenticationType": "oAuthM2M",
     "oAuthClientConfig": {
       "clientId": "<CLIENT ID>",
       "clientSecret": "<SECRET>",
       "authorityUrl": "https://oauth-provider.com/token",
       "useCertificate": false,
       "clientSecret": "<SECRET>"
       "scope": "all-apis"
      },
      "catalog": "immuta",
      "additionalWorkspaceConnections": [
      {
        "workspaceUrl": "workspace-b.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/2222222222222222",
        "authenticationType": "oAuthM2M",
        "oAuthClientConfig": {
          "clientId": "<CLIENT ID>",
          "authorityUrl": "https://oauth-provider.com/token",
          "useCertificate": false,
          "clientSecret": "<SECRET>"
          "scope": "all-apis"
        },
        "catalogs": ["isolated_catalog1"]
      },
      {
        "workspaceUrl": "workspace-c.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/3333333333333333",
        "authenticationType": "token",
        "oAuthClientConfig": {
          "clientId": "<CLIENT ID>",
          "authorityUrl": "https://oauth-provider.com/token",
          "useCertificate": true,
          "publicCertificateThumbprint": "<THUMBPRINT>",
          "oauthPrivateKey": "<PRIVATE KEY CONTENTS>",
          "scope": "all-apis"
        },
        "catalogs": ["isolated_catalog2", "isolated_catalog3"]
      }
    ]
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **oAuthClientConfig** specifies your client ID, client secret, and authority URL. See the [object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-oauth-configuration-object) for details about child parameters. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.
   * additionalWorkspaceConnections.**workspaceURL:** The Databricks workspace URL.
   * additionalWorkspaceConnections.**HTTPpath:** The HTTP path of the compute for the workspace.
   * additionalWorkspaceConnections.**authenticationType**: Specifies the authentication type to use to access the workspace. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace. See the [additionalWorkspaceConnections section](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#additional-workspace-connections) for details about additional authentication types and required and child attributes.
   * additionalWorkspaceConnections.**catalogs:** The catalog[^3] to use for the additional workspace connection.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}

{% hint style="warning" %}
If the integration tries to process an object that is in a bound catalog and none of the specified *additional workspaces* have access to that catalog, the operation will fail and an error will be reported.
{% endhint %}
{% endtab %}
{% endtabs %}

#### Response

The response returns the status of the Databricks Unity Catalog integration configuration connection. See the [response schema reference](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/reference-guides/response-schema) for details about the response schema.

{% tabs %}
{% tab title="200 response" %}
A successful response includes the validation tests statuses.

```json
{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "Metastore validation",
        "status": "passed"
      },
      {
        "name": "Basic Connection Test",
        "result": [
          {
            "1": 1
          }
        ],
        "status": "passed"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="Unsuccessful response" %}
An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/status-codes#post-errors) for a list of statuses, error messages, and troubleshooting guidance.

```json
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Databricks Unity Catalog integration already exists on www.example-workspace.cloud.databricks.com (id = 123456789)"
}
```

{% endtab %}
{% endtabs %}

## Get an integration

```bash
curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'
```

1. Copy the request example.
2. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
3. Replace the **{id}** request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the [<mark style="color:blue;">`GET /integrations`</mark> <mark style="color:blue;">endpoint</mark>](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/integrations-api#get-integrations).

### Response

The response returns a Databricks Unity Catalog integration configuration. See the [response schema reference](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/reference-guides/response-schema) for details about the response schema. An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/status-codes#get-error) for a list of statuses, error messages, and troubleshooting guidance.

```json
{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "Metastore validation",
        "status": "passed"
      },
      {
        "name": "Basic Connection Test",
        "result": [
          {
            "1": 1
          }
        ],
        "status": "passed"
      }
    ]
  },
  "type": "Databricks",
  "autoBootstrap": false,
  "config": {
    "port": 443,
    "workspaceUrl": "www.example-workspace.cloud.databricks.com",
    "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
    "authenticationType": "token",
    "token": "REDACTED",
    "audit": {
      "enabled": false
    },
    "catalog": "immuta"
  }
}
```

## Get all integrations

```bash
curl -X 'GET' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'
```

1. Copy the request example.
2. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.

### Response

The response returns the configuration for all integrations. See the [response schema reference](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/reference-guides/response-schema) for details about the response schema. An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/status-codes#get-error) for a list of statuses, error messages, and troubleshooting guidance.

```json
[
  {
    "id": "1",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "Initial Validation: Basic Connection Test",
          "status": "passed"
        },
        {
          "name": "Initial Validation: Default Warehouse Access Test",
          "status": "passed",
          "result": []
        },
        {
          "name": "Initial Validation: Validate access to Privileged Role",
          "status": "passed",
          "result": []
        },
        {
          "name": "Validate Automatic: Database Does Not Exist",
          "status": "passed"
        },
        {
          "name": "Validate Automatic: Impersonation Role Does Not Exist",
          "status": "skipped"
        },
        {
          "name": "Validate Automatic Bootstrap User Grants",
          "status": "passed"
        }
      ]
    },
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "port": 443,
      "audit": {
        "enabled": false
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "lineage": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "<REDACTED>",
      "password": "<REDACTED>",
      "role": "ACCOUNTADMIN"
    }
  },
  {
    "id": "2",
    "status": "enabled",
    "type": "Databricks",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "Metastore validation",
          "status": "passed"
        },
        {
          "name": "Basic Connection Test",
          "result": [
            {
              "1": 1
            }
          ],
          "status": "passed"
        }
      ]
    },
    "autoBootstrap": true,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "token",
      "token": "REDACTED",
      "audit": {
        "enabled": false
      },
      "catalog": "immuta"
    }
  }
]
```

## Update an integration configuration

Copy the request example, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML.

See the [**config** object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-configuration-objects) for parameter definitions, value types, and additional configuration options.

{% tabs %}
{% tab title="Access token" %}
This example updates the access token.

```bash
curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Databricks",
    "autoBootstrap": true,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "authenticationType": "token",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the integration you want to update.
3. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **token** is the Databricks personal access token. This is the access token for the Immuta service principal.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}
{% endtab %}

{% tab title="Additional workspace connections" %}
{% hint style="warning" %}
To use this feature, you should first [set up a workspace-catalog binding in your Databricks account](https://docs.databricks.com/en/catalogs/binding.html#bind-a-catalog-to-one-or-more-workspaces).
{% endhint %}

This example adds additional workspace connections to an existing configuration.

```bash
curl -X 'PUT' \
   'https://www.organization.immuta.com/integrations/{id}' \
   -H 'accept: application/json' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: <TOKEN> \
   -d '{
  "type": "Databricks",
  "autoBootstrap": true,
  "config": {
    "catalog": "immuta_integration_catalog",
    "workspaceUrl": "workspace-a.cloud.databricks.com",
    "httpPath": "/sql/1.0/warehouses/1111111111111111",
    "authenticationType": "token",
    "audit": {
      "enabled": false
    },
    "additionalWorkspaceConnections": [
      {
        "workspaceUrl": "workspace-b.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/2222222222222222",
        "authenticationType": "oAuthM2M",
        "catalogs": ["isolated_catalog1"]
      },
      {
        "workspaceUrl": "workspace-c.cloud.databricks.com",
        "httpPath": "/sql/1.0/warehouses/3333333333333333",
        "authenticationType": "oAuthM2M",
        "catalogs": ["isolated_catalog2", "isolated_catalog3"]
      }
    ]
  }
}'
```

1. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
2. Replace the **{id}** request parameter with the unique identifier of the integration you want to update.
3. Change the **config** values to your own, where
   * **workspaceUrl** is your Databricks workspace URL.
   * **httpPath** is the HTTP path of your Databricks cluster or SQL warehouse.
   * **oAuthClientConfig** specifies your client ID, client secret, and authority URL. See the [object description](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/payload#databricks-unity-catalog-oauth-configuration-object) for details about child parameters.
   * **catalog** is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.
   * additionalWorkspaceConnections.**workspaceURL:** The Databricks workspace URL.
   * additionalWorkspaceConnections.**HTTPpath:** The HTTP path of the compute for the workspace.
   * additionalWorkspaceConnections.**authenticationType**: Specifies the authentication type to use to access the workspace. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace. *Note: The credentials themselves can be omitted from the payload if they are not being updated.*
   * additionalWorkspaceConnections.**catalogs:** The catalog[^3] to use for the additional workspace connection.

{% hint style="info" %}
**Create a separate Immuta catalog for each Immuta tenant**

If multiple Immuta tenants are connected to your Databricks environment, create a separate **Immuta catalog** for each of those tenants. Having multiple Immuta tenants use the same Immuta catalog causes failures in policy enforcement.
{% endhint %}

{% hint style="warning" %}
If the integration tries to process an object that is in a bound catalog and none of the specified *additional workspaces* have access to that catalog, the operation will fail and an error will be reported.
{% endhint %}
{% endtab %}
{% endtabs %}

### Response

The response returns the status of the Databricks Unity Catalog integration configuration connection. See the [response schema reference](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/reference-guides/response-schema) for details about the response schema.

{% tabs %}
{% tab title="200 response" %}
A successful response includes the validation tests statuses.

```json
{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "Metastore validation",
        "status": "passed"
      },
      {
        "name": "Basic Connection Test",
        "result": [
          {
            "1": 1
          }
        ],
        "status": "passed"
      }
    ]
  }
}
```

{% endtab %}

{% tab title="Unsuccessful response" %}
An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/status-codes#put-errors) for a list of statuses, error messages, and troubleshooting guidance.

```json
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Unable to edit integration with ID 123456789 in current state editing."
}
```

{% endtab %}
{% endtabs %}

## Delete an integration

```bash
curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'
```

1. Copy the request example.
2. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/latest/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
3. Replace the **{id}** request parameter with the unique identifier of the integration you want to delete.

### Response

The response returns the status of the Databricks Unity Catalog integration configuration that has been deleted. See the [response schema reference](https://documentation.immuta.com/latest/developer-guides/api-intro/integrations-api/reference-guides/response-schema) for details about the response schema. An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](https://documentation.immuta.com/latest/developer-guides/api-intro/reference-guides/status-codes#delete-errors) for a list of statuses, error messages, and troubleshooting guidance.

```json
{
  "id": "123456789",
  "status": "deleting",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "Metastore validation",
        "status": "passed"
      },
      {
        "name": "Basic Connection Test",
        "result": [
          {
            "1": 1
          }
        ],
        "status": "passed"
      }
    ]
  }
}
```

[^1]: If configuring the integration using the [automatic setup method](#automatic-setup), the credentials provided must have these privileges.

[^2]: To enable query audit, this user must be an account admin and metastore admin. See [Manage privileges in Unity Catalog](https://docs.databricks.com/en/data-governance/unity-catalog/manage-privileges/index.html) for details.

[^3]: Users may configure one additional workspace connection per catalog.

    Users may still bind a catalog to more than one workspace in Databricks, as long as there is only one additional workspace connection in Immuta, as Immuta requires a single connection from which to control the catalog.