1 of 9

Connections API

The connection API is a REST API which allows users to register a connection to Immuta with a single set of credentials rather than configuring an integration and creating data sources separately. Then Immuta can manage and enforce access controls on your data through that connection.

How-to guides

These guides provide step-by-step instructions for registering and managing your connection.

Reference guide

: This guide defines body parameters for registering connections.

How-to Guides

Register a Connection

Data API reference guide

This section details the /data v1 API, which allows users to register a connection to Immuta with a single set of credentials rather than configuring an integration and creating data sources separately.

Required Immuta permission: APPLICATION_ADMIN

Supported technologies and authentication methods

You can register a connection from the following technologies to Immuta using supported authentication methods:

- AWS access key and secret access key
- AWS IAM role

Register an AWS Lake Formation Connection

Public preview: This connection is available to all accounts.

The connection API is a REST API that allows users to register an AWS Lake Formation connection to Immuta with a single set of credentials rather than configuring an integration and creating data sources separately. Then Immuta can manage and enforce access controls on your data through that connection. To manage your connection, see the Manage a connection reference guide.

Requirements

These are permissions that the user registering the connection must have in order to successfully complete setup.

APPLICATION_ADMIN Immuta permission
Create LF-Tag AWS permission

Prerequisites

. The account in which this is set up is referred to as the admin account. This is the account that you will use to initially configure IAM and AWS Lake Formation permissions to give the Immuta service principal access to perform operations. The user in this account must be able to manage IAM permissions and Lake Formation permissions for all data in the Glue Data Catalog.
No AWS Lake Formation connections configured in the same Immuta instance for the same Glue Data Catalog.
The databases and tables you want Immuta to govern must be . Immuta cannot govern resources that use IAM access control or hybrid access mode. To ensure Immuta can govern your resources, verify that the default Data Catalog settings in AWS are

1. Set up the Immuta service principal

The Immuta service principal is the AWS IAM role that Immuta will assume to perform operations in your AWS account. This role must have all the necessary permissions in AWS Glue and AWS Lake Formation to allow Immuta to register data sources and apply policies.

Create an IAM policy with the following AWS Lake Formation and AWS Glue permissions. You will attach this to your service principal once created.

and select AWS Account as the trusted entity type. This role will be used by Immuta to set up the connection and orchestrate AWS Lake Formation policies. Immuta will assume this IAM role from Immuta's AWS account in order to perform any operations in your AWS account.
Add the IAM policy from step 1 to your service principal. These permissions will allow the service principal to register data sources and apply policies on Immuta's behalf.
Add the service principal as an .

This method follows the principle of least privilege and is the most flexible way of granting permissions to the service principal. LF-Tags cascade down from databases to tables, while allowing for exceptions. This means that when you apply this tag to a database, it will automatically apply to all tables within that database and allow you to remove it from any tables if those should be out of the scope of Immuta’s governance.

Create a new LF-Tag, giving yourself permissions to grant that tag to a user, which will ultimately be your service principal.
1. In the Lake Formation console, navigate to LF-Tags and permissions and click Add LF-Tag. You will need the Create LF-Tag

2. Create the connection in Immuta

POST /data/connection

Copy the request and update the <placeholder_values> with your connection details. Then submit the request.

Find descriptions of the editable attributes in the table below.

Test run

Opt to test and validate the create connection payload using a dry run:

POST /data/connection/test

Immuta will assume this IAM role from Immuta's AWS account in order to perform any operations in your AWS account.

Before proceeding,

Contact your Immuta representative, and Immuta will
1. Provide the AWS account to add to your trust policy.

Payload parameters

Attribute

Description

Required

Response schema

Attribute

Description

Example response

Register a Databricks Unity Catalog Connection

The connection API is a REST API which allows users to register a Databricks Unity Catalog connection to Immuta with a single set of credentials rather than configuring an integration and creating data sources separately. Then Immuta can manage and enforce access controls on your data through that connection. To manage your connection, see the Manage a connection reference guide.

Requirements

APPLICATION_ADMIN Immuta permission
The Databricks user registering the connection and running the script must have the following privileges:
- Metastore admin and account admin
- CREATE CATALOG

See the for more details about Unity Catalog privileges and securable objects.

Prerequisites

Unity Catalog and attached to a Databricks workspace.
Unity Catalog enabled on your Databricks cluster or SQL warehouse. All SQL warehouses have Unity Catalog enabled if your workspace is attached to a Unity Catalog metastore. Immuta recommends linking a SQL warehouse to your Immuta tenant rather than a cluster for both performance and availability reasons.

Complete the following steps to register a Databricks Unity Catalog connection:

Create a service principal in Databricks Unity Catalog with the proper Databricks privileges for Immuta to use to manage policies in Unity Catalog.
Set up Unity Catalog system tables for query audit.
Use the /integrations/scripts/create endpoint to receive a script.

Step 1: Create your service principal

Create a Databricks with the Databricks privileges listed below and set up with personal access token (PAT), which can be , or OAuth machine-to-machine (M2M) authentication. Immuta uses this service principal continuously to orchestrate Unity Catalog policies and maintain state between Immuta and Databricks.

USE CATALOG and MANAGE on all catalogs containing securables registered as Immuta data sources.
USE SCHEMA on all schemas containing securables registered as Immuta data sources.
MODIFY

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

Step 2: Set up query audit

Audit is enabled by default on all Databricks Unity Catalog connections. If you need to turn audit off, set audit to false when generating the script and creating the connection.

. For Databricks Unity Catalog audit to work, Immuta must have, at minimum, the following access.

USE CATALOG on the system catalog
USE SCHEMA on the system.access and system.query schemas

Step 3: Generate the script

POST /integrations/scripts/create

Using the example request, update the <placeholder_values> with your connection details.
Copy the config object to use later in the setup process.
Run the request.

Find descriptions of the editable attributes in the table below and of the full payload in the .

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.

Payload parameters

Attribute

Step 4: Run the script in Databricks Unity Catalog

The previous step will return a script. Copy the script and run it in your Databricks Unity Catalog environment as a user with the privileges listed in .

The script will use the service principal that will authenticate using the authentication that you specified. Additionally, the script will create the catalog you specified.

Step 5: Create the connection in Immuta

Databricks Unity Catalog behavior

If you register a connection and a data object has no subscription policy set on it, Immuta will REVOKE access to the data in Databricks for all Immuta users, even if they had been directly granted access to the table in Unity Catalog.

If you disable a Unity Catalog data source in Immuta, all existing grants and policies on that object will be removed in Databricks for all Immuta users. All existing grants and policies will be removed, regardless of whether they were set in Immuta or in Unity Catalog directly.

POST /data/connection

Copy the request and update the <placeholder_values> with your connection details. Note that the connection details here should match the ones used when generating the script. Then submit the request.

Find descriptions of the editable attributes in the table below and of the full payload in the . All values should be included and those you should not edit are noted.

Test run

Opt to test and validate the create connection payload using a dry run:

POST /data/connection/test

Create a separate Immuta catalog for each Immuta tenant

Payload parameters

Attribute

Response schema

Attribute

Description

Example response

Register an AWS Lake Formation Connection

Public preview: This connection is available to all accounts.

Requirements

These are permissions that the user registering the connection must have in order to successfully complete setup.

APPLICATION_ADMIN Immuta permission
Create LF-Tag AWS permission

Prerequisites

. The account in which this is set up is referred to as the admin account. This is the account that you will use to initially configure IAM and AWS Lake Formation permissions to give the Immuta service principal access to perform operations. The user in this account must be able to manage IAM permissions and Lake Formation permissions for all data in the Glue Data Catalog.
No AWS Lake Formation connections configured in the same Immuta instance for the same Glue Data Catalog.
The databases and tables you want Immuta to govern must be . Immuta cannot govern resources that use IAM access control or hybrid access mode. To ensure Immuta can govern your resources, verify that the default Data Catalog settings in AWS are

1. Set up the Immuta service principal

Create an IAM policy with the following AWS Lake Formation and AWS Glue permissions. You will attach this to your service principal once created.

and select AWS Account as the trusted entity type. This role will be used by Immuta to set up the connection and orchestrate AWS Lake Formation policies. Immuta will assume this IAM role from Immuta's AWS account in order to perform any operations in your AWS account.
Add the IAM policy from step 1 to your service principal. These permissions will allow the service principal to register data sources and apply policies on Immuta's behalf.
Add the service principal as an .

Create a new LF-Tag, giving yourself permissions to grant that tag to a user, which will ultimately be your service principal.
1. In the Lake Formation console, navigate to LF-Tags and permissions and click Add LF-Tag. You will need the Create LF-Tag

2. Create the connection in Immuta

POST /data/connection

Copy the request and update the <placeholder_values> with your connection details. Then submit the request.

Find descriptions of the editable attributes in the table below.

Test run

Opt to test and validate the create connection payload using a dry run:

POST /data/connection/test

Immuta will assume this IAM role from Immuta's AWS account in order to perform any operations in your AWS account.

Before proceeding,

Contact your Immuta representative, and Immuta will
1. Provide the AWS account to add to your trust policy.

Payload parameters

Attribute

Description

Required

Response schema

Attribute

Description

Example response

Register a Databricks Unity Catalog Connection

Requirements

APPLICATION_ADMIN Immuta permission
The Databricks user registering the connection and running the script must have the following privileges:
- Metastore admin and account admin
- CREATE CATALOG

See the for more details about Unity Catalog privileges and securable objects.

Prerequisites

Unity Catalog and attached to a Databricks workspace.
Unity Catalog enabled on your Databricks cluster or SQL warehouse. All SQL warehouses have Unity Catalog enabled if your workspace is attached to a Unity Catalog metastore. Immuta recommends linking a SQL warehouse to your Immuta tenant rather than a cluster for both performance and availability reasons.

Complete the following steps to register a Databricks Unity Catalog connection:

Create a service principal in Databricks Unity Catalog with the proper Databricks privileges for Immuta to use to manage policies in Unity Catalog.
Set up Unity Catalog system tables for query audit.
Use the /integrations/scripts/create endpoint to receive a script.

Step 1: Create your service principal

USE CATALOG and MANAGE on all catalogs containing securables registered as Immuta data sources.
USE SCHEMA on all schemas containing securables registered as Immuta data sources.
MODIFY

Step 2: Set up query audit

Audit is enabled by default on all Databricks Unity Catalog connections. If you need to turn audit off, set audit to false when generating the script and creating the connection.

. For Databricks Unity Catalog audit to work, Immuta must have, at minimum, the following access.

USE CATALOG on the system catalog
USE SCHEMA on the system.access and system.query schemas

Step 3: Generate the script

POST /integrations/scripts/create

Using the example request, update the <placeholder_values> with your connection details.
Copy the config object to use later in the setup process.
Run the request.

Find descriptions of the editable attributes in the table below and of the full payload in the .

Create a separate Immuta catalog for each Immuta tenant

Payload parameters

Attribute

Step 4: Run the script in Databricks Unity Catalog

The previous step will return a script. Copy the script and run it in your Databricks Unity Catalog environment as a user with the privileges listed in .

The script will use the service principal that will authenticate using the authentication that you specified. Additionally, the script will create the catalog you specified.

Step 5: Create the connection in Immuta

Databricks Unity Catalog behavior

POST /data/connection

Find descriptions of the editable attributes in the table below and of the full payload in the . All values should be included and those you should not edit are noted.

Test run

Opt to test and validate the create connection payload using a dry run:

POST /data/connection/test

Create a separate Immuta catalog for each Immuta tenant

Payload parameters

Attribute

Response schema

Attribute

Description

Example response

curl -X 'POST' \ 'https://<your-immuta-url>/data/connection' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: <your-bearer-token>' \ -d '{ "connectionKey": "<your-connection-key-name>", "connection": { "technology": "Databricks", "hostname": "<www.your-workspace.cloud.databricks.com>", "port": <your-Databricks-port>, "httpPath": "<your-Databricks-warehouse-path>", "authenticationType": "oAuthM2M", "oAuthClientConfig": { "useCertificate": false, "clientId": "<your-client-ID>", "clientSecret": "<your-client-secret>", "scope": "all-apis", "authorityUrl": "<your.authority.com>" } }, "settings": { "isActive": false }, "options": { "forceRecursiveCrawl": true }, "nativeIntegration": { "type": "Databricks", "autoBootstrap": false, "unityCatalog": true, "config": { "host": "<www.your-workspace.cloud.databricks.com>", "port": <your-Databricks-port>, "authenticationType": "oAuthM2M", "oAuthClientConfig": { "useCertificate": false, "clientId": "<your-client-ID>", "clientSecret": "<your-client-secret>", "scope": "all-apis", "authorityUrl": "<your.authority.com>" }, "catalog": "<your-immuta-catalog>", "audit": { "enabled": true }, "workspaceIds": ["<your-workspace>", <"another-workspace">], "groupPattern": { "deny": "<your-exemption-group>" }, "jobConfig": { "workspaceDirectoryPath": "/Workspace/ImmutaArtifacts", "jobClusterId": "undefined" } } }'

Connection Registration Payloads Reference Guide

The parameters for configuring a connection in Immuta are outlined in the table below.

Attribute

Description

Required or optional

Accepted values

connectionKey string

A unique name for the connection. Avoid the use of periods (.) or

Required

connection object

See the following object descriptions:

Connection object

The connection object configures the connection between the technology and Immuta. The sections below outline the child parameters specific to each technology.

The oauthPrivateKey object represents your OAuth private key in Snowflake. This object is required if you set oAuthClientCredentials as your authentication type, and useCertificate is set to true. The table below outlines the object's child parameters.

Attribute

Description

Accepted values

Snowflake impersonation object

The impersonation object enables and defines roles for user impersonation for Snowflake. The table below outlines its child parameters.

Parameter

Description

Accepted values

Snowflake workspace object

The workspaces object represents an Immuta project workspace configured for Snowflake. The table below outlines its child parameters.

Parameter

Description

Accepted values

Snowflake lineage object

The lineage object enables Snowflake lineage ingestion. When this setting is enabled, Immuta automatically applies tags added to a Snowflake table to its descendant data source columns in Immuta so you can build policies using those tags to restrict access to sensitive data. The table below outlines its child parameters.

Parameter

Description

Required or optional

Accepted values

The connection API is a REST API which allows users to register a Snowflake connection to Immuta with a single set of credentials rather than configuring an integration and creating data sources separately. Then Immuta can manage and enforce access controls on your data through that connection. To manage your connection, see the Manage a connection reference guide.

Requirements

The following permissions and personas are used in the registration process:

APPLICATION_ADMIN Immuta permission
The Snowflake user registering the connection and running the script must have the following privileges:
- CREATE DATABASE ON ACCOUNT WITH GRANT OPTION

Prerequisites

No Snowflake integration configured in Immuta. If your Snowflake integration is already configured on the app settings page, follow the guide.

Complete the following steps to register a Snowflake connection:

Create an Immuta system account with the proper Snowflake privileges for Immuta to use to manage policies in Snowflake.
Use the /integrations/scripts/create endpoint to receive a script.
Run the script in Snowflake.

Step 1: Set up the Immuta system account

Complete the following actions in Snowflake:

. Immuta will use this system account continuously to orchestrate Snowflake policies and maintain state between Immuta and Snowflake.
with a minimum of the following privileges:
- USAGE on all databases and schemas with registered data sources.

Step 2: Generate the script

POST /integrations/scripts/create

Using the example request, update the <placeholder_values> with your connection details and the authentication credentials for the system account you just created.
Copy the config object to use later in the setup process.
Run the request.

Find descriptions of the editable attributes in the table below and of the full payload in the .

Payload parameters

Attribute

Description

Required

Step 3: Run the script in Snowflake

Snowflake impersonation

If enabling Snowflake impersonation, add the following content to the script that is generated before you run it in Snowflake:

Once you finish configuring the integration, you can grant the IMPERSONATE_USER permission to Immuta users. See the for instructions.

Using your generated script, run it in your Snowflake environment as a user with the permissions listed in the .

The script will use the provided Immuta system user credentials to create the database you specified in the earlier step and set up Immuta-managed resources in Snowflake.

Step 4: Create the connection in Immuta

POST /data/connection

Using the tabs below, copy the request and update the <placeholder_values> with your connection details. The connection details here should match the ones used when generating the script, and the payload from the script generation should be pasted exactly into nativeIntegration. Then submit the request.

Find descriptions of the editable attributes in the table below and of the full payload in the . The recommended setting values are included in the example.

Test run

Opt to test and validate the create connection payload using a dry run:

POST /data/connection/test

Payload parameters

Attribute

Description

Required

Response schema

Attribute

Description

Example response

curl -X 'POST' \ 'https://<your-immuta-url>/data/connection' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: <your-bearer-token>' \ -d '{ "connectionKey": "<your-connection-key-name>", "connection": { "technology": "Snowflake", "hostname": "<your-Snowflake-hostname-url>", "port": <your-Snowflake-port>, "warehouse": "<your-Snowflake-warehouse>", "role": "<your-Snowflake-role>", "authenticationType": "oAuthClientCredentials", "oAuthClientConfig": { "useCertificate": true, "clientId": "<your-client-ID>", "authorityUrl": "<your-example.authority.com>", "scope": "session:role-any", "publicCertificateThumbprint": "<your-certificate-thumbprint>", "resource": "<your-optional-resource>", "oauthPrivateKey": { "keyName": "oauth client certificate", "userFilename": "<your-user-file.pem>", "content": "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->" } } }, "settings": { "isActive": false }, "options": { "forceRecursiveCrawl": true }, "nativeIntegration": { "type": "Snowflake", "autoBootstrap": false, "config": { "authenticationType": "oAuthClientCredentials", "oAuthClientConfig": { "useCertificate": true, "clientId": "<your-client-ID>", "authorityUrl": "<your-example.authority.com>", "scope": "session:role-any", "publicCertificateThumbprint": "<your-certificate-thumbprint>", "resource": "<your-optional-resource>", "oauthPrivateKey": { "keyName": "oauth client certificate", "userFilename": "<your-user-file.pem>", "content": "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->" } } "host": "<your-Snowflake-hostname-url>", "port": <your-Snowflake-port>, "warehouse": "<your-Snowflake-warehouse>", "database": "<your-Snowflake-database>", "impersonation": { "enabled": false }, "audit": { "enabled": true }, "workspaces": { "enabled": false }, "lineage": { "enabled": false }, "userRolePattern": { "exclude": [] } } } }'

Connections API

hashtagHow-to guides

hashtagReference guide

How-to Guides

Register a Connection

hashtagSupported technologies and authentication methods

Register an AWS Lake Formation Connection

hashtagRequirements

hashtagPrerequisites

hashtag1. Set up the Immuta service principal

hashtag2. Create the connection in Immuta

hashtagPayload parameters

hashtagResponse schema

hashtagExample response

Register a Databricks Unity Catalog Connection

hashtagRequirements

hashtagPrerequisites

hashtagStep 1: Create your service principal

hashtagStep 2: Set up query audit

hashtagStep 3: Generate the script

hashtagStep 4: Run the script in Databricks Unity Catalog

hashtagStep 5: Create the connection in Immuta

hashtagResponse schema

hashtagExample response

Register a Connection

hashtagSupported technologies and authentication methods

Connections API

hashtagHow-to guides

hashtagReference guide

How-to Guides

Register an AWS Lake Formation Connection

hashtagRequirements

hashtagPrerequisites

hashtag1. Set up the Immuta service principal

hashtag2. Create the connection in Immuta

hashtagPayload parameters

hashtagResponse schema

hashtagExample response

Register a Databricks Unity Catalog Connection

hashtagRequirements

hashtagPrerequisites

hashtagStep 1: Create your service principal

hashtagStep 2: Set up query audit

hashtagStep 3: Generate the script

hashtagStep 4: Run the script in Databricks Unity Catalog

hashtagStep 5: Create the connection in Immuta

hashtagResponse schema

hashtagExample response

Deregister a Connection

hashtagStep 1: Generate the cleanup script

hashtagPath parameters

hashtagResponse

hashtagStep 2: Delete the connection in Immuta

hashtagPath parameters

hashtagResponse schema

hashtagExample response

hashtagStep 3: Run the cleanup script in your data platform

Manage a Connection

hashtagGET /data/connection/{connectionKey}

hashtagPath parameters

hashtagResponse schema

hashtagExample response

hashtagGET /data/object/{objectPath}

hashtagPath parameters

hashtagResponse schema

hashtagExample response

hashtagPOST /data/object/search/{objectPath}

hashtagPath parameters

hashtagQuery parameters

hashtagResponse schema

hashtagExample response

hashtagPUT /data/connection/{connectionKey}

hashtagPath parameters

hashtagBody parameters

hashtagResponse schema

hashtagExample response

hashtagPOST /data/crawl/{objectPath}

hashtagPath parameters

hashtagQuery parameters

hashtagResponse schema

How-to guides

Reference guide

Supported technologies and authentication methods

Requirements

Prerequisites

1. Set up the Immuta service principal

2. Create the connection in Immuta

Payload parameters

Response schema

Example response

Requirements

Prerequisites

Step 1: Create your service principal

Step 2: Set up query audit

Step 3: Generate the script

Step 4: Run the script in Databricks Unity Catalog

Step 5: Create the connection in Immuta

Response schema

Example response

Supported technologies and authentication methods

How-to guides

Reference guide

Requirements

Prerequisites

1. Set up the Immuta service principal

2. Create the connection in Immuta

Payload parameters

Response schema

Example response

Requirements

Prerequisites

Step 1: Create your service principal

Step 2: Set up query audit

Step 3: Generate the script

Step 4: Run the script in Databricks Unity Catalog

Step 5: Create the connection in Immuta

Response schema

Example response

Step 1: Generate the cleanup script

Path parameters

Response

Step 2: Delete the connection in Immuta

Path parameters

Response schema

Example response

Step 3: Run the cleanup script in your data platform

`GET` `/data/connection/{connectionKey}`

Path parameters

Response schema

Example response

`GET` `/data/object/{objectPath}`

Path parameters

Response schema

Example response

`POST` `/data/object/search/{objectPath}`

Path parameters

Query parameters

Response schema

Example response

`PUT` `/data/connection/{connectionKey}`

Path parameters

Body parameters

Response schema

Example response

`POST` `/data/crawl/{objectPath}`

Path parameters

Query parameters

Response schema

Example response

`PUT` `/data/settings/{objectPath}`

Path parameters

Body parameters

Response schema

Example response

`DELETE` `/data/object/{objectPath}`

Path parameters

Response schema

Example response

Connection object

Snowflake connection object