Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The integrations API is a REST API that allows you to integrate your remote data platform with Immuta so that Immuta can manage and enforce access controls on your data.
This task-based guide includes end-to-end instructions for implementing your integration - from authenticating with the API to mapping your users into Immuta so that they can access policy-enforced data. A basic request and payload example is provided for configuring each integration.
These guides provide step-by-step instructions for creating and managing your integration and include configuration setting examples that vary in complexity.
These guides define request and body parameters, response schema, and common error messages.
The integrations API is a REST API that allows you to integrate your remote data platform with Immuta so that Immuta can manage and enforce access controls on your data.
To configure an integration using the API, you must have the APPLICATION_ADMIN Immuta permission.
There are two methods for making an authenticated request to the integrations API. Select a tab below for instructions.
Generate your API key on the API Keys tab on your profile page and save the API key somewhere secure.
You will pass this API key in the authorization header when you make a request, as illustrated in the example below:
Generate your API key on the API Keys tab on your profile page and save the API key somewhere secure.
Save your API key in a .json file.
Make the following request to the authentication endpoint:
You will receive a response that includes your bearer token. Pass that bearer token in the Authorization header when you make a request, as illustrated in the example below:
Use the POST /integrations endpoint to configure the integration so that Immuta can enforce access controls on tables registered as Immuta data sources. See a section below for a sample request and details about configuring your integration.
Private preview: The Amazon S3 integration is available to select accounts. Reach out to your Immuta representative for details.
Copy the request example.
Change the config values to your own, where
name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.
awsAccountId is the ID of your AWS account.
awsRegion is the account's AWS region (such as us-east1).
awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.
awsLocationPath is the base S3 location prefix that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.
awsAccessKeyId is the AWS access key ID of the AWS account configuring the integration.
awsSecretAccessKey is the AWS secret access key of the AWS account configuring the integration.
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
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.
Private preview: This integration is available to select accounts. Reach out to your Immuta representative for details.
Copy the request example. The example uses JSON format, but the request also accepts YAML.
Change the config values to your own, where
role is the Google Cloud role used to connect to Google BigQuery.
datasetSuffix is the suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore.
dataset is the name of the BigQuery dataset to provision inside of the project for Immuta metadata storage.
location is the dataset's location, which can be any valid GCP location (such as us-east1).
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
authenticationType is the type of authentication to use when connecting to Redshift.
username and password are the credentials for the system account that can act on Redshift objects and configure the integration.
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
authenticationType is the type of authentication to use when connecting to Snowflake.
Navigate to the Immuta App Settings page and click the Integrations tab.
Click your enabled Starburst (Trino) integration and copy the configuration snippet displayed.
Map usernames and create policies before you register your metadata to ensure that policies are enforced on tables and views immediately.
Build global policies in Immuta to enforce access controls:
Register your metadata using the API or Immuta UI:
API how-to guides
UI how-to guides:
See the following how-to guides for configuration examples and steps for creating, managing, or disabling your integration:
See the following reference guides for information about the integrations API endpoints, payloads, and responses:
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
Several different accounts are used to set up and maintain the Databricks Unity Catalog integration. The permissions required for each are outlined below.
Immuta account (required): This user configures the integration on the app settings page in Immuta. To access the app settings page, this user needs the following permission:
APPLICATION_ADMIN Immuta permission
Databricks service principal (required): This service principal is used continuously by Immuta to orchestrate Unity Catalog policies and maintain state between Immuta and Databricks. In the , Immuta also uses this service principal to create the Immuta-managed catalog. This service principal needs the following Databricks privileges:
CREATE CATALOG privilege on the Unity Catalog metastore. This is only required if you have Immuta . If a separate user will run the Immuta script in Databricks to manually configure the integration, that Databricks user account needs this privilege instead.
OWNER permission on the Immuta catalog you configure.
OWNER privilege on one of the securables below so that Immuta can administer Unity Catalog row-level and column-level security controls.
on catalogs with schemas and tables registered as Immuta data sources. This permission could also be applied by granting OWNER on a catalog to a Databricks group that includes the Immuta service principal to allow for multiple owners.
on schemas with tables registered as Immuta data sources.
on all tables registered as Immuta data sources - if the OWNER permission cannot be applied at the catalog- or schema-level. In this case, each table registered as an Immuta data source must individually have the OWNER permission granted to the Immuta service principal.
USE CATALOG and USE SCHEMA on parent catalogs and schemas of tables registered as Immuta data sources so that the Immuta service principal can SELECT and MODIFY securables within the parent catalog and schema.
SELECT and MODIFY on all tables registered as Immuta data sources so that the Immuta service principal can grant and revoke access to tables and apply Unity Catalog row- and column-level security controls.
For native query audit (optional)
USE CATALOG on the system catalog
USE SCHEMA on the system.access schema
SELECT on the following system tables:
system.access.audit
system.access.table_lineage
system.access.column_lineage
Databricks account (recommended): This user account can manually configure the integration in Databricks to create the Immuta-managed catalog. To do so, this account requires the following Databricks privileges:
CREATE CATALOG on the Unity Catalog metastore
ACCOUNT ADMIN on the Unity Catalog metastore for native query audit (optional)
Opt to enable native query audit for Unity Catalog:
USE CATALOG on the system catalog
USE SCHEMA on the system.access schema
SELECT on the following system tables:
system.access.audit
system.access.table_lineage
system.access.column_lineage
You have two options for configuring your Databricks Unity Catalog integration. Select the method you prefer below to navigate to configuration instructions:
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.
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.
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.
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.
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.
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.
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.
A successful response includes the validation tests statuses.
To manually configure the integration, complete the following steps:
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.
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.
Run the script returned in the response in your Databricks environment.
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.
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.
Run the script returned in the response in your Databricks environment.
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.
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.
Run the script returned in the response in your Databricks environment.
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.
Response
The response returns the script for you to run in your environment.
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.
workspaceUrl is your Databricks workspace URL.
httpPath is the HTTP path of your Databricks cluster or SQL warehouse.
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.
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.
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.
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.
A successful response includes the validation tests statuses.
Copy the request example.
Copy the request example.
You have two options for updating your integration. Follow the steps that match your initial configuration of autoBootstrap:
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.
This example updates the access token.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
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.
This example adds additional workspace connections to an existing configuration.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
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.
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.
A successful response includes the validation tests statuses.
To manually update the integration, complete the following steps:
Copy the request example, and replace the values with your own as directed to generate the script. The example provided uses JSON format, but the request also accepts YAML.
This example updates the access token.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
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.
Run the script returned in the response in your Databricks environment.
This example adds additional workspace connections to an existing configuration.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
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.
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.
Run the script returned in the response in your Databricks environment.
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.
Response
The response returns the script for you to run in your Databricks environment.
This example updates the access token.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
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.
This example adds additional workspace connections to an existing configuration.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
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.
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.
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.
A successful response includes the validation tests statuses.
Copy the request example.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
Private preview: The Amazon S3 integration is available to select accounts. Reach out to your Immuta representative for details.
The Amazon S3 resource allows you to create, configure, and manage your . In this integration, Immuta provides coarse-grained access controls for data in S3 by performing permission grants using the Access Grants API so that users don't have to manage individual IAM policies themselves.
Use the /integrations endpoint to
S3 integration enabled in Immuta; contact your Immuta representative to enable this integration
; contact your Immuta representative to get this feature enabled
No location is registered in your AWS Access Grants instance before configuring the integration in Immuta
APPLICATION_ADMIN Immuta permission to configure the integration
CREATE_S3_DATASOURCE Immuta permission to register S3 data sources
The AWS account credentials or optional AWS IAM role you provide Immuta when configuring the integration must
have ownership of the buckets Immuta will enforce policies on
have the following permissions to create locations and issue grants:
s3:CreateAccessGrant
s3:CreateAccessGrantsLocation
s3:DeleteAccessGrant
s3:DeleteAccessGrantsLocation
s3:GetAccessGrant
s3:GetAccessGrantsInstance
s3:GetAccessGrantsInstanceForPrefix
s3:GetAccessGrantsInstanceResourcePolicy
s3:GetAccessGrantsLocation
s3:ListAccessGrants
s3:ListAccessGrantsInstances
s3:ListAccessGrantsLocations
iam:PassRole
iam:GetRole
sts:AssumeRole
sts:SetSourceIdentity
sts:SetContext
s3:GetObject
s3:GetObjectVersion
s3:GetObjectAcl
s3:GetObjectVersionAcl
s3:ListMultipartUploadParts
s3:PutObject
s3:PutObjectAcl
s3:PutObjectVersionAcl
s3:DeleteObject
s3:DeleteObjectVersion
s3:AbortMultipartUpload
s3:ListBucket
s3:ListAllMyBuckets
iam:passRole
If you use server-side encryption with AWS Key Management Service (AWS KMS) keys to encrypt your data, the following permissions are required for the IAM role in the policy. If you do not use this feature, do not include these permissions in your IAM policy:
kms:Decrypt
kms:GenerateDataKey
This request configures the integration using the AWS access key authentication method.
Copy the request example. The example uses JSON format, but the request also accepts YAML.
Change the config values to your own, where
name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.
awsAccountId is the ID of your AWS account.
awsRegion is the account's AWS region (such as us-east1).
awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.
awsLocationPath is the base S3 location prefix that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.
awsAccessKeyId is the AWS access key ID of the AWS account configuring the integration.
awsSecretAccessKey is the AWS secret access key of the AWS account configuring the integration.
Copy the request example. The example uses JSON format, but the request also accepts YAML.
Change the config values to your own, where
name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.
awsAccountId is the ID of your AWS account.
awsRegion is the account's AWS region (such as us-east1).
awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.
awsLocationPath is the base S3 location that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.
A successful response includes the validation tests statuses.
Copy the request example.
Copy the request example.
Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values from above to your own. The editable values listed below are the only parameters that can change from the integration's existing configuration. The required parameters listed below must match the integration's existing configuration.
editable values:
name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.
authenticationType is the method used to authenticate with AWS when configuring the S3 integration (accepted values are auto or accessKey).
awsAccessKeyId is the AWS access key ID for the AWS account editing the integration.
awsSecretAccessKey is the AWS secret access key for the AWS account editing the integration.
required values from existing configuration:
awsRoleToAssume is the optional AWS IAM role ARN Immuta assumes when interacting with AWS.
awsAccountId is the ID of your AWS account.
awsRegion is the account's AWS region (such as us-east1).
awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.
awsLocationPath is the base S3 location that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.
A successful response includes the validation tests statuses.
Copy the request example.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
Copy the request example. The example uses JSON format, but the request also accepts YAML.
Change the dataSources values to your own, where
dataSourceName is the name of your data source.
prefix creates a data source for the prefix, bucket, or object provided in the path. If the data source prefix ends in a wildcard (), it protects all items starting with that prefix. If the data source prefix ends without a wildcard (), it protects a single object.
In the Redshift integration, Immuta generates policy-enforced views in your configured Redshift schema for tables registered as Immuta data sources.
Use the /integrations endpoint to
APPLICATION_ADMIN Immuta permission
A Redshift cluster with an RA3 node is required for the multi-database integration. You must use a Redshift RA3 instance type because Immuta requires cross-database views, which are only supported in Redshift RA3 instance types. For other instance types, you may configure a single-database integration using one of the :
Configure the integration with an existing database that contains the external tables. In the steps below, specify an existing database in Redshift as the database in which Immuta will add the Immuta-managed schemas and views instead of creating a new database.
Create a new database as specified in the steps below, and then re-create all of your external tables in that database.
For automated installations, the credentials provided must be a Superuser or have the ability to create databases and users and modify grants.
Account used to configure or edit the integration must have the following Redshift permissions:
CREATE DATABASE
CREATE USER
REVOKE ALL PRIVILEGES ON DATABASE
GRANT TEMP ON DATABASE
MANAGE GRANTS ON ACCOUNT
You have two options for configuring your Redshift integration:
These privileges will be used to create and configure a new Immuta-managed database within the specified Redshift instance. The credentials are not stored or saved by Immuta, and Immuta doesn’t retain access to them after initial setup is complete.
You can create a new account for Immuta to use that has these privileges, or you can grant temporary use of a pre-existing account. By default, the pre-existing account with appropriate privileges is a Superuser. If you create a new account, it can be deleted after initial setup is complete.
Copy the request example from one of the sections below, 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.
This request specifies userPassword as the authentication type for the Immuta system user. The username and password provided are credentials for a system account that can manage the database.
Change the config values to your own, where
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
username and password are the credentials for the system account that can act on Redshift objects and configure the integration.
This request uses Okta as the authentication type for the Immuta system user and enables impersonation to allow Immuta administrators to grant users permission to query Redshift data as other Immuta users.
Change the config values to your own, where
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
A successful response includes the validation tests statuses.
To manually configure the integration, complete the following steps:
Copy the request example from one of the tabs below, and replace the values with your own as directed to generate the first script. The examples provided use JSON format, but the request also accepts YAML.
This request specifies userPassword as the authentication type for the Immuta system user. The username and password provided are credentials for a system account that can manage the database.
Change the config values to your own, where
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
username and password are the credentials for the system account that can act on Redshift objects and configure the integration.
Run the script returned in the response in the Redshift initialDatabase specified in the payload.
This request uses Okta as the authentication type for the Immuta system user and enables impersonation to allow Immuta administrators to grant users permission to query Redshift data as other Immuta users.
Change the config values to your own, where
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
Run the script returned in the response in the Redshift initialDatabase specified in the payload.
Response
The response returns the script for you to run in the Redshift initialDatabase.
This request specifies userPassword as the authentication type for the Immuta system user. The username and password provided are credentials for a system account that can manage the database.
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
username and password are the credentials for the system account that can act on Redshift objects and configure the integration.
Run the script returned in the response in the database created by the first script.
This request uses Okta as the authentication type for the Immuta system user and enables impersonation to allow Immuta administrators to grant users permission to query Redshift data as other Immuta users.
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
Run the script returned in the response in the database created by the first script.
Response
The response returns the script for you to run in the database created by the first script.
This request specifies userPassword as the authentication type for the Immuta system user. The username and password provided are credentials for a system account that can manage the database.
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
username and password are the credentials for the system account that can act on Redshift objects and configure the integration.
This request uses Okta as the authentication type for the Immuta system user and enables impersonation to allow Immuta administrators to grant users permission to query Redshift data as other Immuta users.
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
A successful response includes the validation tests statuses.
Copy the request example.
Copy the request example.
You have two options for updating your integration. Follow the steps that match your initial configuration of autoBootstrap:
Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
A successful response includes the validation tests statuses.
To manually update the integration, complete the following steps:
Copy the request example, and replace the values with your own as directed to generate the script. The example provided uses JSON format, but the request also accepts YAML.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
Run the script returned in the response in your Redshift environment.
Response
The response returns the script for you to run in your Redshift environment.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
host is the URL of your Redshift account.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
A successful response includes the validation tests statuses.
Copy the request example.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
If you set
autoBootstrap to true when enabling the integration, specify the authenticationType and the credentials you used to configure the integration in the payload, as illustrated in the example.
.
Replace the values in the request with your Immuta URL and .
Replace the values in the request with your Immuta URL and , and change the config values to your own, where
The example sets autoBootstrap to true, which grants Immuta one-time access to credentials to configure the resources in your Azure Synapse Analytics environment for you. If you set autoBootstrap to false, you must manually in your Azure Synapse Analytics environment yourself before making the request.
For more configuration examples, see the . For information about the configuration payload, see the .
Replace the values in the request with your Immuta URL and , and change the config values to your own, where
For more configuration examples, see the . For information about the configuration payload, see the .
by either using the Google Cloud console or the provided Immuta script.
Replace the Immuta URL and with your own.
credential is the Google BigQuery service account JSON keyfile credential content. See the for guidance on generating and downloading this keyfile.
For more configuration examples, see the guide. For information about the configuration payload, see the .
Replace the values in the request with your Immuta URL and , and change the config values to your own, where
The example sets autoBootstrap to true, which grants Immuta one-time access to credentials to configure the resources in your Redshift environment for you. If you set autoBootstrap to false, you must manually in your Redshift environment yourself before making the request.
For more configuration examples, see the . For information about the configuration payload, see the .
Replace the values in the request with your Immuta URL and , and change the config values to your own, where
username and password are credentials of a Snowflake account attached to a role with . These credentials are not stored; they are used by Immuta to configure the integration.
role is a Snowflake role that has been granted .
The example sets autoBootstrap to true, which grants Immuta one-time access to credentials to configure the resources in your Snowflake environment for you. If you set autoBootstrap to false, you must manually in your Snowflake environment yourself before making the request.
For more configuration examples, see the . For information about the configuration payload, see the .
Replace the values in the request with your Immuta URL and .
Follow the steps in the configure the Immuta system access control plugin in or section to add the configuration in the appropriate immuta-access-control.properties file to finish configuring your cluster.
to Immuta to ensure Immuta properly enforces policies and audits user queries.
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 for the metastore associated with the Databricks workspace.
OAuth machine-to-machine (M2M) authentication: If using this method, follow for the Immuta service principal. This service principal must have the for the metastore associated with the Databricks workspace.
In Databricks, with the .
.
.
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 . Otherwise, . For Databricks Unity Catalog audit to work, the service principal must have the following access at minimum:
: Immuta creates the catalogs, schemas, tables, and functions using the service principal you created.
: 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 .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
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 for details about additional authentication types and required and child attributes.
additionalWorkspaceConnections.catalogs: The to use for the additional workspace connection.
The response returns the status of the Databricks Unity Catalog integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
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 for details about additional authentication types and required and child attributes.
additionalWorkspaceConnections.catalogs: The to use for the additional workspace connection.
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 .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the 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.
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 for details about additional authentication types and required and child attributes.
additionalWorkspaceConnections.catalogs: The to use for the additional workspace connection.
The response returns the status of the Databricks Unity Catalog integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
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 .
The response returns a Databricks Unity Catalog integration configuration. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
The response returns the configuration for all integrations. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
(autoBootstrap is true)
(autoBootstrap is false)
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
additionalWorkspaceConnections.catalogs: The to use for the additional workspace connection.
The response returns the status of the Databricks Unity Catalog integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
additionalWorkspaceConnections.catalogs: The to use for the additional workspace connection.
Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
Replace the Immuta URL and with your own.
oAuthClientConfig specifies your client ID, client secret, and authority URL. See the for details about child parameters.
additionalWorkspaceConnections.catalogs: The to use for the additional workspace connection.
The response returns the status of the Databricks Unity Catalog integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
The response returns the status of the Databricks Unity Catalog integration configuration that has been deleted. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
. AWS supports one Access Grants instance per region per AWS account.
. You will add this role to your integration configuration in Immuta so that Immuta can register this role with your Access Grants location. The AWS documentation linked above gives a complete policy example, but your policy should include the following permissions:
with the following permissions, and attach the policy to the IAM role you created to grant the permissions to the role. The AWS documentation linked above gives a complete example, but the policy should at least include the following permissions:
that Immuta can use to create Access Grants locations and issue grants. This role must have the S3 permissions listed in the .
Replace the Immuta URL and with your own.
This request configures the integration using the automatic authentication method, which searches and obtains credentials using the . This method requires a configured and is only supported if you're using a self-managed deployment of Immuta. Work with your Immuta representative to customize your deployment and set up an IAM role for a service account that can give Immuta the credentials to set up the integration.
Replace the Immuta URL and with your own.
See the for parameter definitions, value types, and additional configuration options.
The response returns the status of the S3 integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
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 .
The response returns an S3 integration configuration. See the for details about the response schema. An unsuccessful response returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
The response returns the configuration for all integrations. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
The response returns the status of the Amazon S3 integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
The response returns the status of the S3 integration configuration that has been deleted. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
Change the integrationsID to the . This ID can be retrieved with the .
See the for parameter definitions and value types.
The response returns the ID, name, and prefix of the data source. See the for details about the response schema. An unsuccessful response returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
: Grant Immuta one-time use of credentials to automatically configure your Redshift environment and the integration. When performing an automated installation, Immuta requires temporary, one-time use of credentials with the Redshift permissions listed in the .
: Run the Immuta script in your Redshift environment yourself to configure your Redshift environment and the integration. The specified role used to run the bootstrap needs to have the Redshift permissions listed in the .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
okta specifies your username, password, appId, idpHost, and role. See the for details about child parameters.
The response returns the status of the Redshift integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
okta specifies your username, password, appId, idpHost, and role. See the for details about child parameters.
Copy the request example from one of the tabs below, 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 .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
okta specifies your username, password, appId, idpHost, and role. See the for details about child parameters.
Copy the request example from one of the tabs below, 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 .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
okta specifies your username, password, appId, idpHost, and role. See the for details about child parameters.
The response returns the status of the Redshift integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
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 .
The response returns a Redshift integration configuration. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
The response returns the configuration for all integrations. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
(autoBootstrap is true)
(autoBootstrap is false)
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
okta specifies your username, password, appId, idpHost, and role. See the for details about child parameters.
The response returns the status of the Redshift integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
okta specifies your username, password, appId, idpHost, and role. See the for details about child parameters.
Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
okta specifies your username, password, appId, idpHost, and role. See the for details about child parameters.
The response returns the status of the Redshift integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
autoBootstrap to false when enabling the integration, use the script endpoint (for integrations that were not successfully created) or the endpoint (for integrations that were successfully created) to remove Immuta-managed resources from your environment. Then, make the request above without including a payload to remove the integration from Immuta.
The response returns the status of the Redshift integration configuration that has been deleted. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
In the Snowflake integration, Immuta manages access to Snowflake tables by administering Snowflake row access policies and column masking policies on those tables, allowing users to query tables directly in Snowflake while dynamic policies are enforced.
Use the /integrations endpoint to
APPLICATION_ADMIN Immuta permission
Snowflake Enterprise account
Role used to configure, edit, or remove the integration needs to have the following Snowflake privileges:
CREATE DATABASE ON ACCOUNT WITH GRANT OPTION
CREATE ROLE ON ACCOUNT WITH GRANT OPTION
CREATE USER ON ACCOUNT WITH GRANT OPTION
MANAGE GRANTS ON ACCOUNT WITH GRANT OPTION
APPLY MASKING POLICY ON ACCOUNT WITH GRANT OPTION
APPLY ROW ACCESS POLICY ON ACCOUNT WITH GRANT OPTION
You have two options for configuring your Snowflake integration:
Automatic setup: Grant Immuta one-time use of credentials to automatically configure your Snowflake environment and the integration. When performing an automated installation, Immuta requires temporary, one-time use of credentials with the Snowflake privileges listed in the requirements section.
These permissions will be used to create and configure a new Immuta-managed database within the specified Snowflake instance. The credentials are not stored or saved by Immuta, and Immuta doesn’t retain access to them after initial setup is complete.
You can create a new account for Immuta to use that has these permissions, or you can grant temporary use of a pre-existing account. By default, the pre-existing account with appropriate permissions is ACCOUNTADMIN. If you create a new account, it can be deleted after initial setup is complete.
Manual setup: Run the Immuta script in your Snowflake environment yourself to configure your Snowflake environment and the integration. The specified role used to run the bootstrap needs to have the Snowflake privileges listed in the requirements section.
Select the section below that matches your authentication method.
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 for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and API key with your own.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
username and password are credentials of a Snowflake account attached to a role with the privileges outlined above. These credentials are not stored; they are used by Immuta to configure the integration.
role is a Snowflake role that has been granted the privileges outlined above.
Replace the Immuta URL and API key with your own.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.
privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.
The response returns the status of the Snowflake integration configuration connection. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Best practices
The account you create for Immuta should only be used for the integration and should not be used as the credentials for creating data sources in Immuta; doing so will cause issues. Instead, create a separate, dedicated READ-ONLY account for creating and registering data sources within Immuta.
To manually configure the integration, complete the following steps:
Select the tab below that matches your authentication method.
Copy the request example and replace the values with your own as directed to generate the script. The examples provided use JSON format, but the request also accepts YAML.
See the config object description for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and API key with your own.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.
Run the script returned in the response in your Snowflake environment.
Replace the Immuta URL and API key with your own.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.
privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.
Run the script returned in the response in your Snowflake environment.
In this example, Snowflake External OAuth is used to authenticate the system account user, ensuring secure communication between Immuta and Snowflake. To use this authentication method, autoBootstrap must be false.
Replace the Immuta URL and API key with your own.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces.enabled specifies whether Immuta project workspaces are enabled for Snowflake.
workspaces.warehouses is a list of warehouses that workspace users have usage privileges on.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username is the system account user that can act on Snowflake objects and configure the integration.
oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.
Run the script returned in the response in your Snowflake environment.
Response
The response returns the script for you to run in your environment.
Select the tab below that matches your authentication method.
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 parameters and values you provide in this payload must match those you provided when generating the script.
See the config object description for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and API key with your own.
Pass the same payload you sent when generating the script, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.
Replace the Immuta URL and API key with your own.
Pass the same payload you sent when generating the script, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.
privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.
In this example, Snowflake External OAuth is used to authenticate the system account user, ensuring secure communication between Immuta and Snowflake. To use this authentication method, autoBootstrap must be false.
Replace the Immuta URL and API key with your own.
Pass the same payload you sent when generating the script, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
workspaces specifies whether Immuta project workspaces are enabled for Snowflake. See the object description for details about child parameters.
oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.
The response returns the status of the Snowflake integration configuration connection. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
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 GET /integrations endpoint.
The response returns the Snowflake integration configuration. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
The response returns the configuration for all integrations. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
You have two options for updating your integration. Follow the steps that match your initial configuration of autoBootstrap:
automatic update (autoBootstrap is true)
manual update (autoBootstrap is false)
Select the section below that matches your authentication method.
Copy the request example and replace the values with your own as directed to update the integration settings. The examples provided use JSON format, but the request also accepts YAML.
See the config object description for parameter definitions, value types, and additional configuration options.
This request updates the configuration to enable query audit in Snowflake.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
username and password are credentials of a Snowflake account attached to a role with the privileges outlined above. These credentials are not stored; they are used by Immuta to enable or disable configuration settings.
role is a Snowflake role that has been granted the privileges outlined above.
This request updates the configuration to enable query audit in Snowflake.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.
privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.
The response returns the status of the Snowflake integration configuration. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
To manually update the integration, complete the following steps:
Select the tab below that matches your authentication method.
Copy the request example and replace the values with your own as directed to generate the script. The examples provided use JSON format, but the request also accepts YAML.
See the config object description for parameter definitions, value types, and additional configuration options.
This request updates the configuration to enable query audit in Snowflake.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.
Run the script returned in the response in your Snowflake environment.
This request updates the configuration to enable query audit in Snowflake.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.
privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.
Run the script returned in the response in your Snowflake environment.
This request updates the configuration to disable Snowflake workspaces for the integration.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username is the system account user that can act on Snowflake objects and configure the integration.
oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.
Run the script returned in the response in your Snowflake environment.
Response
The response returns the script for you to run in your environment.
Select the section below that matches your authentication method.
Copy the request example and replace the values with your own as directed to update the integration settings. The examples provided use JSON format, but the request also accepts YAML. The payload you provide must match the one you provided when generating the updated script.
See the config object description for parameter definitions, value types, and additional configuration options.
This request updates the configuration to enable query audit in Snowflake.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Pass the same payload you sent when generating the script, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username and password are the credentials for the system account that can assume the role to manage the database and administer Snowflake masking and row access policies.
This request updates the configuration to enable query audit in Snowflake.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Pass the same payload you sent when generating the script, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces represents an Immuta project workspace configured for Snowflake. See the object description for child parameters.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
username is the system account user that can assume the role to manage the database and administer Snowflake masking and row access policies.
privateKey is your private key. If you are using curl, replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
connectArgs is used to set PRIV_KEY_FILE_PWD if the private key is encrypted.
This request updates the configuration to disable Snowflake workspaces and enable Snowflake query audit for the integration.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Pass the same payload you sent when generating the script, where
host is the URL of your Snowflake account.
warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
database is the name of a new empty database that the Immuta system user will manage and store metadata in.
impersonation specifies whether user impersonation is enabled. See the object description for child parameters.
audit specifies whether query audit is enabled for Snowflake. See the object description for child parameters.
workspaces specifies whether Immuta project workspaces are enabled for Snowflake. See the object description for details about child parameters.
oAuthClientConfig specifies your provider, client ID, client secret, authority URL, and your encoded public and private keys. See the object description for details about child parameters.
The response returns the status of the Snowflake integration configuration. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
If you set
autoBootstrap to true when enabling the integration, specify the authenticationType and the credentials you used to configure the integration in the payload, as illustrated in the example. See the Integrations API endpoints guide for details.
autoBootstrap to false when enabling the integration,
Make the request above without including a payload to remove the integration from Immuta.
Run the generated script in Snowflake.
The response returns the status of the Snowflake integration configuration that has been deleted. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Private preview: This integration is available to select accounts. Reach out to your Immuta representative for details.
The Google BigQuery resource allows you to create, configure, and manage your Google BigQuery integration. In this integration, Immuta generates policy-enforced views in your configured Google BigQuery dataset for tables registered as Immuta data sources.
Use the /integrations endpoint to
APPLICATION_ADMIN Immuta permission
Google BigQuery integration enabled in Immuta (work with your Immuta representative to enable this integration)
To execute the Immuta script from your command line to create a Google Cloud service account and role, you must be authenticated to the gcloud CLI utility as a user with all of the following roles:
roles/iam.roleAdmin
roles/iam.serviceAccountAdmin
roles/serviceusage.serviceUsageAdmin
Create a Google Cloud service account and role by either using the Google Cloud console or the provided Immuta script.
Copy the request example. The example uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and API key with your own.
Change the config values to your own, where
role is the Google Cloud role used to connect to Google BigQuery.
datasetSuffix is the suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore.
dataset is the name of the BigQuery dataset to provision inside of the project for Immuta metadata storage.
location is the dataset's location, which can be any valid GCP location (such as us-east1).
credential is the Google BigQuery service account JSON keyfile credential content. See the Google documentation for guidance on generating and downloading this keyfile.
See the config object description for parameter definitions, value types, and additional configuration options.
The response returns the status of the Google BigQuery integration configuration connection. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
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 GET /integrations endpoint.
The response returns a Google BigQuery integration configuration. See the response schema reference for details about the response schema. An unsuccessful response returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
The response returns the configuration for all integrations. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example, which updates the private key. The example uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
role is the Google Cloud role used to connect to Google BigQuery.
datasetSuffix is the suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore.
dataset is the name of the BigQuery dataset to provision inside of the project for Immuta metadata storage.
location is the dataset's location, which can be any valid GCP location (such as us-east1).
credential is the Google BigQuery service account JSON keyfile credential content. See the Google documentation for guidance on generating and downloading this keyfile.
See the config object description for parameter definitions, value types, and additional configuration options.
The response returns the status of the Google BigQuery integration configuration connection. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
The response returns the status of the Google BigQuery integration configuration that has been deleted. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
The Starburst (Trino) resource allows you to create and manage your Starburst (Trino) integration. In this integration, Immuta policies are translated into Starburst rules and permissions and applied directly to tables within users’ existing catalogs.
Use the /integrations endpoint to
APPLICATION_ADMIN Immuta permission
A valid Starburst Enterprise license
To configure the Starburst (Trino) integration, complete the following steps:
Copy the request example. The example provided uses JSON format, but the request also accepts YAML.
Replace the Immuta URL and API key with your own.
The response returns the status of the Starburst (Trino) integration configuration connection. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Navigate to the Immuta App Settings page and click the Integrations tab.
Click your enabled Starburst (Trino) integration and copy the configuration snippet displayed.
Copy the request example.
Replace the Immuta URL and API key with your own.
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 GET /integrations endpoint.
The response returns a Starburst (Trino) integration configuration and the Immuta API key used to configure the Starburst cluster. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Copy the request example.
Replace the Immuta URL and API key with your own.
The response returns the configuration for all integrations. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Cluster restart required
To update your API key in Starburst (Trino), you must shut down your cluster, generate and update the API key, and then restart your cluster. If you do not shut down your cluster, generating a new API key using the endpoint below will cause downtime for your deployment.
Copy the request example below and replace these values:
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the Starburst (Trino) integration you want to regenerate the Immuta API key for.
Once you make this request, your old Immuta API key will be deleted and will no longer be valid.
The response includes your new Immuta API key. Replace the old immuta.apikey value in the Immuta access control properties file with this new key.
The response includes your new Immuta API key.
Copy the request example.
Replace the Immuta URL and API key with your own.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
The response returns the status of the Starburst (Trino) integration configuration that has been deleted. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
The reference guides in this section define the integrations API endpoints, request and body parameters, and response schema.
The integrations API endpoints allow you to create, update, get, and delete integrations and generate scripts to run in your data platform to manually set up or remove Immuta-managed resources.
Consult this guide for endpoint descriptions and examples.
The integrations API request payloads accept JSON or YAML format, and each integration has parameters and objects specific to the data platform.
Consult this guide for parameter value types, requirements, definitions, and accepted values.
The response returns the status of the integration configuration in JSON format.
Consult this guide for response schema definitions and integration state definitions.
The integrations API uses standard HTTP status codes. Status codes specific to the integrations API are described in this reference guide.
Consult this guide for a list of status codes, integration states, common error messages, and troubleshooting guidance.
The how-to guides in this section illustrate how to integrate your remote data platform with Immuta so you can manage and enforce access controls on your data.
Private preview: The Amazon S3 integration is available to select accounts. Reach out to your Immuta representative for details.
Immuta's Amazon S3 integration allows users to apply subscription policies to data in S3 to restrict what prefixes, buckets, or objects users can access. To enforce access controls on this data, Immuta creates S3 grants that are administered by S3 Access Grants, an AWS feature that defines access permissions to data in S3.
Follow this guide to configure and manage your Amazon S3 integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.
In this integration, Immuta generates policy-enforced views in a schema in your configured Azure Synapse Analytics Dedicated SQL pool for tables registered as Immuta data sources.
Follow this guide to configure and manage your Azure Synapse Analytics integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.
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.
Follow this guide to configure and manage your Databricks Unity Catalog integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.
Private preview: This integration is available to select accounts. Reach out to your Immuta representative for details.
In this integration, Immuta generates policy-enforced views in your configured Google BigQuery dataset for tables registered as Immuta data sources.
Follow this guide to configure and manage your Google BigQuery integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.
Immuta generates policy-enforced views in your configured Redshift schema for tables registered as Immuta data sources.
Follow this guide to configure and manage your Redshift integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.
Immuta manages access to Snowflake tables by administering Snowflake row access policies and column masking policies on those tables, allowing users to query tables directly in Snowflake while dynamic policies are enforced.
Follow this guide to configure and manage your Snowflake integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.
Immuta policies are translated into Starburst rules and permissions and applied directly to tables within users’ existing catalogs.
Follow this guide to configure and manage your Starburst (Trino) integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.
The table below outlines the response schema for all integration configurations.
| Property | Description |
|---|---|
The status property in the response schema shows the status of the integration. The table below provides definitions for each status and the state of the integration configuration.
The validationResults object provides details about the status of each test Immuta runs to validate the the integration configuration.
| Attribute | Description | Possible values |
|---|---|---|
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
The integrations API returns HTTP status codes, error codes, and messages in JSON format.
The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for the error.
| Code | Text | Description |
|---|---|---|
The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for each error.
| Code | Text | Description |
|---|---|---|
The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for each error.
| Code | Text | Description |
|---|---|---|
The table below provides the HTTP code, the error code, an example message, and troubleshooting guidance for each error.
The integrations resource allows you to create, configure, and manage your integration. How Immuta manages and administers policies in your data platform varies by integration.
To configure or manage an integration, users must have the APPLICATION_ADMIN Immuta permission.
| Method | Endpoint | Description |
|---|---|---|
Gets all integration configurations.
The response returns the configuration for all integrations. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Creates an integration configuration that allows Immuta to manage access policies on data registered in Immuta.
When you connect Immuta to your AWS account, the awsLocationPath is the base S3 location prefix that Immuta will use for this connection when registering S3 data sources.
This request configures the integration using the AWS access key authentication method.
When you connect Immuta to your Azure Synapse Analytics account, the schema you specify is where all the policy-enforced views will be created and managed by Immuta.
This request creates a Databricks Unity Catalog integration configuration that allows Immuta to administer Unity Catalog policies on data registered in Immuta.
When you connect Immuta to your Google BigQuery account, the dataset you specify is where all the policy-enforced views will be created and managed by Immuta.
When you connect Immuta to your Redshift account, the Immuta system user will use the database you specify to manage and store metadata. The initial database (REDSHIFT_SAMPLE_DATA, in the request below) is an existing Redshift database that Immuta connects to in order to create the Immuta-managed database (immuta, in the request below).
This request specifies userPassword as the authentication type for the Immuta system user. The username and password provided are credentials for a system account that can manage the database.
When you connect Immuta to your Snowflake account, the warehouse you specify is the default pool of compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
This request specifies userPassword authentication type. The username and password provided are credentials of a Snowflake account attached to a role with these privileges. These credentials are not stored; they are used by Immuta to configure the integration.
When you configure the Starburst (Trino) integration, Immuta generates an API key and configuration snippet on the Immuta app settings page that you will use to configure your Starburst cluster.
The request accepts a JSON or YAML payload with the parameters outlined below.
The response returns the status of the integration configuration connection. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Deletes the integration configuration you specify in the request.
For Amazon S3 integrations, Databricks Unity Catalog integrations, Google BigQuery integrations, Starburst (Trino) integrations, or integration configurations with autoBootstrap set to false, no payload is required to delete the integration.
For the integrations below, the request accepts a JSON or YAML payload when autoBootstrap is set to true. See the payload description for your integration for parameters and details:
The response returns the status of the integration configuration that has been deleted. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Gets the integration configuration you specify in the request.
The response returns an integration configuration. See the response schema reference 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 for a list of statuses, error messages, and troubleshooting guidance.
Updates an existing integration configuration.
This request changes the name of the integration.
This request enables user impersonation for the Azure Synapse Analytics integration.
This request updates the access token.
This request updates the private key for the Google BigQuery integration.
This request enables user impersonation for the Redshift integration.
This request enables auditing queries run in Snowflake.
The request accepts a JSON or YAML payload with the parameters outlined below.
The response returns the status of the integration configuration connection. See the response schema reference for details about the response schema.
A successful response includes the validation tests statuses.
An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Regenerates an Immuta API key for the configured integration.
This request regenerates an Immuta API key for the configured Starburst (Trino) integration. Once you make this request, your old Immuta API key will be deleted and will no longer be valid. See the Configure a Starburst (Trino) integration page for instructions on updating your Starburst (Trino) integration to use the new API key.
The response returns the new Immuta API key. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages page for a list of statuses, error messages, and troubleshooting guidance.
Gets the status of the integration specified in the request.
The response returns the status of the specified integration. An unsuccessful request returns the HTTP status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.
Creates a script to remove Immuta-managed resources from your platform. This endpoint is for Azure Synapse Analytics, Redshift, and Snowflake integrations that were not successfully created and, therefore, do not have an integration ID.
For Azure Synapse Analytics integrations, you must also make a request to the /integrations/scripts/post-cleanup endpoint to create another script that will finish removing Immuta-managed resources from the platform.
The request accepts a JSON or YAML payload with the parameters outlined below.
The response returns the script that you will run in your Azure Synapse Analytics, Redshift, or Snowflake environment.
Once you have run the script,
use the DELETE /integrations/{id} endpoint to delete your Redshift or Snowflake integration in Immuta:
use the /integrations/scripts/post-cleanup endpoint to create another script that will finish removing Immuta-managed resources from your Azure Synapse Analytics platform.
Creates a script for you to run manually to set up objects and resources for Immuta to manage and enforce access controls on your data. This endpoint is available for Azure Synapse Analytics, Databricks Unity Catalog, Redshift, and Snowflake integrations.
The request accepts a JSON or YAML payload with the parameters outlined below.
The response returns the script that you will run in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment.
Creates a script to remove Immuta-managed resources from your platform. This endpoint is for Azure Synapse Analytics, Redshift, and Snowflake integrations that were successfully created.
The response returns the script that you will run in your Azure Synapse Analytics, Redshift, or Snowflake environment.
Once you have run the script, use the DELETE /integrations/{id} endpoint to delete your integration in Immuta:
Creates a script for you to run manually to edit objects and resources managed by Immuta in your platform. This endpoint is available for Azure Synapse Analytics, Databricks Unity Catalog, Redshift, and Snowflake integrations.
The request accepts a JSON or YAML payload with the parameters outlined below.
The response returns the script that you will run in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment. Once you have run the script, use the PUT /integrations/{id} endpoint to finish editing your integration:
Creates the first script for you to run manually to set up objects and resources for Immuta to manage and enforce access controls on your data in Azure Synapse Analytics or Redshift integrations.
The request accepts a JSON or YAML payload with the parameters outlined below.
The response returns the script that you will run in your Azure Synapse Analytics or Redshift environment.
Once you have run this script, use the /integrations/scripts/create endpoint to generate a script to finish creating the Immuta-managed resources in your platform.
Creates a second script to remove the final Immuta-managed resources from your Azure Synapse Analytics platform. This endpoint is for Azure Synapse Analytics integrations that were not successfully created and, therefore, do not have an integration ID.
Before making a request like the one below, you must make a request to the /integrations/scripts/cleanup endpoint to create the first script that will remove the initial Immuta-managed resources from the platform.
The request accepts a JSON or YAML payload with the parameters outlined below.
The response returns the script that you will run in your Azure Synapse Analytics environment.
Once you have run the script, use the DELETE /integrations/{id} endpoint to delete your integration in Immuta by following the Delete Azure Synapse Analytics integration instructions.
See the following how-to guides for configuration examples and steps for creating, managing, or deleting your integration:
The parameters for configuring an integration in Immuta are outlined in the table below.
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
The config object configures the S3 integration. The table below outlines its child parameters.
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
The table below outlines the parameters for creating an S3 data source.
The table below outlines the response schema for successful requests.
The config object configures the Azure Synapse Analytics integration. The table below outlines its child parameters.
The impersonation object enables and defines roles for user impersonation for Azure Synapse Analytics. The table below outlines its child parameters.
The credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.
The metadataDelimiters object specifies the delimiters that Immuta uses to store profile data in Azure Synapse Analytics. The table below outlines its child parameters.
The config object configures the Databricks Unity Catalog integration. The table below outlines its child parameters.
The additionalWorkspaceConnections array allows you to configure additional workspace connections for your Databricks Unity Catalog integration. The table below outlines its child attributes.
The audit object enables Databricks Unity Catalog query audit. The table below outlines its child parameter.
The groupPattern object excludes the listed group from having data policies applied in the Databricks Unity Catalog integration. This account-level group should be used for privileged users and service accounts that require an unmasked view of data. The table below outlines its child parameters.
The proxyOptions object represents your proxy server configuration in Databricks Unity Catalog. The table below outlines the object's child attributes.
The oAuthClientConfig object represents your OAuth configuration in Databricks Unity Catalog. This object is required if you set oAuthM2M as your authentication type in the Databricks Unity Catalog integration configuration. The table below outlines the object's child parameters.
The config object configures the Google BigQuery integration. The table below outlines its child parameters.
The config object configures the Redshift integration. The table below outlines its child parameters.
The authentication type and credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.
The impersonation object enables and defines roles for user impersonation for Redshift. The table below outlines its child parameters.
The okta object represents your Okta configuration. This object is required if you set okta as your authentication type in the Redshift integration configuration. The table below outlines its child parameters.
The config object configures the Snowflake integration. The table below outlines its child parameters.
The audit object enables Snowflake query audit. The table below outlines its child parameter.
The authentication type and credentials you used when configuring your integration are required in the payload when autoBootstrap was set to true when setting up your integration. For integration configurations with autoBootstrap set to false, no payload is required when deleting the integration.
The impersonation object enables and defines roles for user impersonation for Snowflake. The table below outlines its child parameters.
The lineage object enables Snowflake native 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.
The oAuthClientConfig object represents your OAuth configuration in Snowflake. This object is required if you set oAuthClientCredentials as your authentication type in the Snowflake integration configuration, and you must set autoBootstrap to false. The table below outlines the object's child parameters.
The userRolePattern object excludes roles and users from authorization checks in the Snowflake integration. The table below outlines its child parameter.
The workspaces object represents an Immuta project workspace configured for Snowflake. The table below outlines its child parameters.
The Azure Synapse Analytics resource allows you to create, configure, and manage your Azure Synapse Analytics integration. In this integration, Immuta generates policy-enforced views in a schema in your configured Azure Synapse Analytics Dedicated SQL pool for tables registered as Immuta data sources.
Use the /integrations endpoint to
APPLICATION_ADMIN Immuta permission
A running Dedicated SQL pool
Account used to configure or edit the integration must have the Azure Synapse Analytics permission to manage GRANTS
You have two options for configuring your Azure Synapse Analytics integration:
: Grant Immuta one-time use of credentials to automatically configure your Azure Synapse Analytics environment and the integration. When performing an automated installation, Immuta requires temporary, one-time use of credentials with the permission to manage GRANTS.
: Run the Immuta script in your Azure Synapse Analytics environment yourself to configure your environment and the integration. The specified role used to run the bootstrap needs to have the permission to manage GRANTS.
Copy the request example from one of the tabs below, 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.
Change the config values to your own, where
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.
Change the config values to your own, where
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
A successful response includes the validation tests statuses.
To manually configure the integration, complete the following steps:
Copy the request example from one of the tabs below, and replace the values with your own as directed to generate the script. The examples provided use JSON format, but the request also accepts YAML.
Change the config values to your own, where
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
Run the script returned in the response in your Azure Synapse Analytics environment.
This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.
Change the config values to your own, where
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
Run the script returned in the response in your Azure Synapse Analytics environment.
Response
The response returns the script for you to run in your environment.
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
Run the script returned in the response in your Azure Synapse Analytics environment.
This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
Run the script returned in the response in your Azure Synapse Analytics environment.
Response
The response returns the script for you to run in your environment.
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
A successful response includes the validation tests statuses.
Copy the request example.
Copy the request example.
You have two options for updating your integration. Follow the steps that match your initial configuration of autoBootstrap:
Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
A successful response includes the validation tests statuses.
To manually update the integration, complete the following steps:
Copy the request example, and replace the values with your own as directed to generate the script. The example provided uses JSON format, but the request also accepts YAML.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
Change the config values to your own, where
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
Run the script returned in the response in your Azure Synapse Analytics environment.
Response
The response returns the script for you to run in your environment.
Replace the {id} request parameter with the unique identifier of the integration you want to update.
host is the URL of your Azure Synapse Analytics account.
schema is the name of the Immuta-managed schema where all your secure views will be created and stored.
database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
A successful response includes the validation tests statuses.
Copy the request example.
Replace the {id} request parameter with the unique identifier of the integration you want to delete.
If you set
autoBootstrap to true when enabling the integration, include the credentials you used to configure the integration in the payload, as illustrated in the example.
autoBootstrap to false when enabling the integration,
make the request above without including a payload to remove the integration from Immuta.
| Test name | Description | Message |
|---|---|---|
| Test name | Description | Message |
|---|---|---|
| Test name | Description | Message |
|---|---|---|
| Test name | Description | Message |
|---|---|---|
| Test name | Description | Message |
|---|---|---|
| Test name | Description | Message |
|---|---|---|
| Code | Text | Description |
|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional |
|---|---|---|
| Parameter | Description | Required or optional |
|---|---|---|
| Parameter | Description | Required or optional |
|---|---|---|
| Parameter | Description | Required or optional |
|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional |
|---|---|---|
| Parameter | Description | Required or optional |
|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Property | Description |
|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Required or optional | Accepted values |
|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Attribute | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Accepted values |
|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Required or optional | Accepted values |
|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Required or optional | Default values | Accepted values |
|---|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
| Parameter | Description | Default values | Accepted values |
|---|---|---|---|
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
The response returns the status of the Azure Synapse Analytics integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
Copy the request example from one of the tabs below, 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 .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
Copy the request example from one of the tabs below, 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 .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
The response returns the status of the Azure Synapse Analytics integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
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 .
The response returns an Azure Synapse Analytics integration configuration. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
The response returns the configuration for all integrations. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
(autoBootstrap is true)
(autoBootstrap is false)
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
The response returns the status of the Azure Synapse Analytics integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when .
See the for parameter definitions, value types, and additional configuration options.
Replace the Immuta URL and with your own.
Pass the same payload you sent when , where
impersonation specifies whether user impersonation is enabled. See the for child parameters.
metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the for child parameters.
The response returns the status of the Azure Synapse Analytics integration configuration connection. See the for details about the response schema.
An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
Replace the Immuta URL and with your own.
use the script endpoint (for integrations that were not successfully created) or the endpoint (for integrations that were successfully created) to remove Immuta-managed resources from your environment,
use the script endpoint to finish removing Immuta-managed resources from your environment,
The response returns the status of the Azure Synapse Analytics integration configuration that has been deleted. See the for details about the response schema. An unsuccessful request returns the status code and an error message. See the for a list of statuses, error messages, and troubleshooting guidance.
There is no existing integration matching this configuration
Verifies that the integration configuration does not match an existing one.
-
The provided integration name is unique across Immuta S3 integrations
Verifies that the name of the integration does not match an existing S3 integration name.
"The Immuta service account does not end with expected value."
The provided access grants location role is a valid ARN format
Verifies that the access grants location role is in the correct format.
"The specified access grants location role is not a valid ARN format."
The provided AWS credentials allow fetching the caller's identity via the AWS STS API
Verifies that the integration can use the AWS STS API to get the caller's identity using the provided credentials.
"Found user ID [], ARN [] using STS."
An AWS Access Grants instance is configured in the provided AWS account and region
Verifies that an Access Grants instance has been created in the specified AWS account and region.
"AccessDenied: Unable to retrieve the access grants instance for account, region: AWS responded with code [403], name [AccessDenied] and message [Access Denied] for request ID []."
The provided S3 path exists and Immuta can list prefixes
Verifies that Immuta can access and list prefixes for the provided S3 path.
"Immuta does not have access to the requested path [s3://]. Without access, Immuta will be unable to assist with S3 path discovery during data source creation."
An AWS Access Grants location does not yet exist for the provided path
Verifies that an Access Grants location has not already been registered for the specified S3 path.
"AccessDenied: Unable to list S3 access grants locations for account [], location scope []: AWS responded with code [403], name [AccessDenied] and message [Access Denied] for request ID []."
Initial validation: connect
Verifies that Immuta can connect to Azure Synapse Analytics.
"Unable to connect to host."
Initial validation: delimiters test
Verifies that the delimiters are unique.
"Hash delimiter and array delimiter must not have the same value."
Validate automatic: impersonation role does not exist
Verifies that the user impersonation role specified in the request payload does not already exist.
"Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name."
Validate Immuta system user can manage database
Verifies that the specified user can manage the database.
"User does not have permission to manage database."
Basic connection test
Verifies that Immuta can connect to Databricks Unity Catalog.
"Could not connect to host, please confirm you are using valid connection parameters."
Manual catalog setup
Verifies that the catalog and tables used by Immuta are present and have the correct permissions. This test is run when autoBootstrap is false in the Databricks Unity Catalog integration configuration.
"Encountered an error looking up catalog metadata for catalog."
Metastore validation
Verifies that the Unity Catalog metastore is assigned to the specified workspace.
"No metastore is assigned to workspace."
Basic validation: connection can be made to BigQuery
Verifies that Immuta can connect to Google BigQuery.
"Could not connect to the remote BigQuery connection."
Basic validation: Immuta service account postfix
Verifies that the service account ends with the expected value of @<projectId>.iam.gserviceaccount.com.
"The Immuta service account does not end with expected value."
Basic validation: non-matching service account in key file
Verifies that the service account matches the one provided in the keyfile.
"The service account does not match the service account in the provided key file."
Basic validation: verify service account not being used for data source connection credentials
Verifies that credentials that have been used to create Google BigQuery data sources are not the same credentials used to configure the Google BigQuery integration.
"Native BigQuery doesn't support the reuse of service accounts for integrations that are currently being used for data sources."
Validate manual: [dataset - create]
Verifies that the custom role assigned to the service account has the permissions to create the dataset.
Message includes a permission warning.
Validate manual: [dataset - delete]
Verifies that the custom role assigned to the service account has the permissions to delete the Immuta-managed dataset.
Message includes a permission warning.
Initialize validation: [dataset - exists]
Verifies that this dataset does not already exist.
"An existing Immuta instance exists. Delete this dataset to continue."
Validate manual: [table - create]
Verifies that the custom role assigned to the service account has the permissions to create Immuta-managed tables.
Message includes a permission warning.
Validate manual: [table - delete]
Verifies that the custom role assigned to the service account has the permissions to delete Immuta-managed tables.
Message includes a permission warning.
Validate manual: [table - get]
Verifies that the custom role assigned to the service account has the permissions to get Immuta-managed tables.
Message includes a permission warning.
Validate manual: [table - insert]
Verifies that the custom role assigned to the service account has the permissions to insert rows in Immuta-managed tables.
Message includes a permission warning.
Validate manual: [table - update]
Verifies that the custom role assigned to the service account has the permissions to update Immuta-managed tables.
Message includes a permission warning.
Initial validation: basic connection test
Verifies that Immuta can connect to Redshift.
"Unable to connect to host."
Validate automatic: database does not exist
Verifies that the database specified in the request payload does not already exist.
"The database already exists. If this database can be safely dropped, please do so and try again. Alternatively, specify a different database name."
Validate automatic: impersonation role does not exist
Verifies that the user impersonation role specified in the request payload does not already exist.
"Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name."
Initial validation: basic connection test
Verifies that Immuta can connect to the Snowflake database.
"Unable to connect to host."
Initial validation: default warehouse access test
Verifies that the default warehouse exists and that the Immuta system account user has permissions to act on the default warehouse specified.
"Unable to access default warehouse. If this was a manual installation, ensure that the user has been granted usage on the specified warehouse."
Initial validation: table grants role prefix is unique
Verifies that the prefix for Snowflake table grants does not already exist. If this prefix already exists, navigate to the Integration Settings section on the Immuta app settings page to disable Snowflake table grants, re-enable it, and then update the role prefix.
"The Snowflake table grants role prefix IMMUTA is used by another Immuta instance connected to the same Snowflake host. Please update the table grants role prefix for this Immuta instance and try again."
Initial validation: validate access to privileged role
Verifies that the privileged role exists and that it has been assigned to the Immuta system account user.
"User does not have access to the privileged role."
Validate automatic bootstrap user grants
Verifies the credentials of the user executing the Immuta bootstrap script in Snowflake.
-
Validate automatic: database does not exist
Verifies that the database specified in the request payload does not already exist.
"The database already exists. If this database can be safely dropped, please do so and try again. Alternatively, specify a different database name."
Validate automatic: impersonation role does not exist
Verifies that the user impersonation role specified in the request payload does not already exist.
"Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name."
404
Not found
Example: "No Integration found with ID 5." The request failed because the integration with the given ID was not found. Use the GET /integrations endpoint to list all integration configurations to find the correct ID.
400
Bad request
Example: "Credentials are not required for disable unless the integration was configured automatically. If you need to update your integration credentials, use PUT to update the integration before disabling." The request failed because the payload provided authentication credentials for a manually bootstrapped integration. Remove the authentication credentials from the payload.
400
Bad request
Example: "Integrations that are automatically configured require privileged credentials to disable. Please provide them in your payload." The request failed because the integration was created with autoBootstrap set to true, and privileged credentials were not provided in the request payload to delete the integration. Provide the credentials you used to configure your Azure Synapse Analytics, Redshift, or Snowflake integration.
400
Bad request
Example: "Credentials are not required to disable a Databricks Unity Catalog integration. If you need to update your integration credentials, use PUT to update the integration before disabling." The request failed because the payload provided authentication credentials for a Databricks Unity Catalog integration. Remove the authentication credentials from the payload.
404
Not found
Example: "No integration found with ID 5." The request failed because the integration with the given ID was not found. Use the GET /integrations endpoint to list all integration configurations to find the correct ID.
409
Conflict
Example: "Unable to edit integration with ID 10 in current state editing." The request failed because the integration is currently being modified or deleted. Use the GET /integrations/{id}/status endpoint to determine when the integration has finished updating. Then, delete the integration.
422
Unprocessable entity
Example: "Unable to delete integration with ID 7, validation failed." The request failed because a validation test failed. See the validation results object documentation for a list of validation test messages and errors to address the issue.
400
Bad Request
Example: "Use PUT /integrations/1 endpoint to update connection information for Snowflake integration on host test-account.snowflakecomputing.com (id = 1) that previously failed to create." The request failed because the integration previously failed to create. The message you receive includes the ID and host of the integration that failed. Use the PUT /integrations/{id} endpoint to update the connection information for that integration to create it.
409
Conflict
Example: "Snowflake integration already exists on test-account.snowflakecomputing.com (id = 1)." The request failed because an integration already exists on the host. Use the integration ID provided in the error message to delete or modify the existing integration. Ensure that the name and config parameters in the new configuration do not conflict with your existing integration.
422
Unprocessable entity
Example: "Validation of prerequisite setup failed. Unable to create integration." The request failed because a validation test failed. See the validation results object documentation for a list of validation test messages and errors to address the issue.
422
Unprocessable entity
Example: "Processing Error: Error trying to get the current metastore info." The request failed because Immuta could not find the Databricks metastore information.
400
Bad request
Example: "Unable to edit integration due to changes of non-editable attribute(s)." The request failed because an attribute was changed that cannot be edited. The error message includes a list of the attributes that the request attempted to change.
404
Not found
Example: "No integration found with ID 5." The request failed because the integration with the given ID was not found. Use the GET /integrations endpoint to list all integration configurations to find the correct ID.
409
Conflict
Example: "Unable to edit integration with ID 10 in current state editing." The request failed because the integration is currently being modified or deleted. Use the GET /integrations/{id}/status endpoint to determine when the integration has finished updating. Then, modify the integration. If the integration has been deleted, use the POST /integrations endpoint to re-create the integration.
422
Unprocessable entity
Example: "Unable to edit integration with ID 7, validation failed." The request failed because a validation test failed. See the validation results object documentation for a list of validation test messages and errors to address the issue.
GET
Gets all integration configurations
POST
Creates an integration
DELETE
Deletes a configured integration
GET
Gets an integration configuration
PUT
Updates a configured integration
POST
Regenerates an Immuta API key for the configured integration
GET
Gets the status of the specified integration
POST
Creates a script to remove Immuta-managed resources from your platform for integrations that were not successfully created
POST
Creates a script to set up Immuta-managed resources in your platform
POST
Creates a script to remove Immuta-managed resources from your platform for integrations that were successfully configured
POST
Creates a script to edit existing Immuta-managed resources in your platform
POST
Creates the first script to set up Immuta-managed resources in your Azure Synapse Analytics or Redshift platform
POST
Creates the second script to remove Immuta-managed resources from your Azure Synapse Analytics integration if it was not successfully created
type string
The type of integration to configure.
Required
-
Azure Synapse Analytics
Databricks
Google BigQuery
Native S3
Redshift
Snowflake
Trino
autoBootstrap boolean
When true, Immuta will automatically configure the integration in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment for you. When false, you must set up your environment manually before configuring the integration with the API. This parameter must be set to false in the Amazon S3 and Google BigQuery configurations. See the specific how-to guide for configuring your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, Snowflake.
Required for all integrations except Starburst (Trino)
-
true or false
config object
This object specifies the integration settings. See the config object description for your integration for details: Amazon S3, Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake.
Required for all integrations except Starburst (Trino)
-
-
dryRun boolean
When true, the integration configuration will not actually be created, and the response returns the validation tests statuses.
Optional
id number
The unique identifier of the integration configuration.
Required
dryRun boolean
When true, the integration configuration will not actually be deleted, and the response returns the validation tests statuses.
Optional
forceDisable boolean
When true, the integration will be deleted in Immuta. Users must manually remove all Immuta objects in the remote data platform.
Optional
id number
The unique identifier of the integration configuration.
Required
type string
The type of integration to configure.
Required
-
Azure Synapse Analytics
Databricks
Google BigQuery
Redshift
Snowflake
autoBootstrap boolean
When true, Immuta will automatically configure the integration in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment for you. When false, you must set up your environment manually before configuring the integration with the API. This parameter must be set to false in the Google BigQuery configuration. See the specific how-to guide for configuring other integrations: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, Snowflake.
Required
-
true or false
config object
This object specifies the integration settings. See the config object description for your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake.
Required
-
-
dryRun boolean
When true, the integration configuration will not actually be updated, and the response returns the validation tests statuses.
Optional
id number
The unique identifier of the integration configuration.
Required
type string
The type of integration to clean up.
Required
-
Azure Synapse Analytics
Redshift
Snowflake
autoBootstrap boolean
Set to false to specify that you will run the script in your environment yourself to clean up the integration resources. See the Azure Synapse Analytics, Redshift, or Snowflake manual setup section for details.
Required
-
false
config object
This object specifies the integration settings. See the config object description for your integration for details: Azure Synapse Analytics, Redshift, or Snowflake.
Required
-
-
type string
The type of integration to configure.
Required
-
Azure Synapse Analytics
Databricks
Redshift
Snowflake
autoBootstrap boolean
Set to false to specify that you will run the script in your environment yourself to configure the integration. You must run the Immuta script before creating the integration. See the Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake manual setup guides for details.
Required
-
false
config object
This object specifies the integration settings. See the config object description for your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake.
Required
-
-
type string
The type of integration to configure.
Required
-
Azure Synapse Analytics
Databricks
Redshift
Snowflake
autoBootstrap boolean
Set to false to specify that you will run the script in your environment yourself to configure the integration. You must run the Immuta script before creating the integration. See the Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake manual setup guides for details.
Required
-
false
config object
This object specifies the integration settings. Some settings cannot be changed once an integration is configured. See the config object description for your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake.
Required
-
-
type string
The type of integration to configure.
Required
-
Azure Synapse Analytics
Redshift
autoBootstrap boolean
Set to false to specify that you will run the script in your environment yourself to configure the integration. You must run the Immuta script before creating the integration. See the Azure Synapse Analytics or Redshift manual setup guides for details.
Required
-
false
config object
This object specifies the integration settings. See the config object description of the Azure Synapse Analytics or Redshift integration configuration for details.
Required
-
-
type string
The type of integration to clean up.
Required
-
Azure Synapse Analytics
autoBootstrap boolean
Set to false to specify that you will run the script in your environment yourself to clean up the integration resources. See the Azure Synapse Analytics manual setup section for details.
Required
-
false
config object
This object specifies the integration settings. See the config object description of Azure Synapse Analytics for details.
Required
-
-
type string
The type of integration to configure.
Required
-
autoBootstrap boolean
When true, Immuta will automatically configure the integration in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment for you. When false, you must set up your environment manually before configuring the integration with the API. This parameter must be set to false in the Amazon S3 and Google BigQuery configurations. See the specific how-to guide for configuring your integration for details: Azure Synapse Analytics, Databricks Unity Catalog, Redshift, Snowflake.
Required for all integrations except Starburst (Trino)
-
true or false
config object
This object specifies the integration settings. See the config object description for your integration for details: Amazon S3, Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake.
Required for all integrations except Starburst (Trino)
-
-
name string
A name for the integration that is unique across all Amazon S3 integrations configured in Immuta.
Required
-
-
awsAccountId string
The ID of your AWS account.
Required
-
-
awsRegion string
The AWS region to use.
Required
-
Any valid AWS region (us-east-1, for example)
awsLocationRole string
The AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee. When a grantee accesses S3 data, the AWS Access Grants service attaches session policies and assumes this role in order to vend scoped down credentials to the grantee. This role needs full access to all paths under the S3 location prefix.
Required
-
-
awsLocationPath string
The base S3 location prefix that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.
Required
-
-
awsRoleToAssume string
The optional AWS IAM role ARN Immuta assumes when interacting with AWS.
Optional
[]
-
authenticationType string
The method used to authenticate with AWS when configuring the S3 integration.
Required
-
auto
accessKey
awsAccessKeyId string
The AWS access key ID for the AWS account configuring the integration.
Required when authenticationType is accessKey.
-
-
awsSecretAccessKey string
The AWS secret access key for the AWS account configuring the integration.
Required when authenticationType is accessKey.
-
-
port number
The port to use when connecting to your S3 Access Grants instance.
Optional
443
0-65535
type string
The type of integration.
Required
-
Native S3
integrationId number
The unique identifier of the S3 integration.
Required
-
-
dataSources.dataSourceName string
The name of the S3 data source you want to create.
Required
-
-
dataSources.prefix string
The S3 prefix that creates a data source for the prefix, bucket, or object provided in the path.
Required
-
-
dataSourceId integer
The unique identifier of the data source.
prefix string
The S3 path of the prefix, bucket, or object used to create the data source.
dataSourceName string
The name of the data source.
host string
The URL of your Azure Synapse Analytics account.
Required
-
Valid URL hostnames.
database string
Name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.
Required
-
-
schema string
Name of the Immuta-managed schema where all your secure views will be created and stored.
Required
-
-
authenticationType string
The method used to authenticate with Azure Synapse Analytics when configuring the integration.
Required
-
userPassword
username string
The username of the system account that can act on Azure Synapse Analytics objects and configure the integration.
Required
-
-
password string
The password of the system account that can act on Azure Synapse Analytics objects and configure the integration.
Required
-
-
metadataDelimiters object
This object is a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for parameters.
Optional
See the object description for default values.
-
port number
The port to use when connecting to your Azure Synapse Analytics account host.
Optional
1433
0-65535
impersonation object
Enables user impersonation. See the impersonation object description for parameters.
Optional
Disabled by default. See the impersonation object description for parameters.
-
connectArgs string
The connection string arguments to pass to the ODBC driver when connecting as the Immuta system user.
Optional
-
-
enabled boolean
When true, enables user impersonation.
false
true or false
role string
The name of the user impersonation role.
IMMUTA_IMPERSONATION
-
authenticationType string
The type of authentication used when originally configuring the Azure Synapse Analytics integration.
Required
userPassword
username string
The username of the system account that configured the integration.
Required if autoBootstrap was true when setting up the integration.
-
password string
The password of the system account that configured the integration.
Required if autoBootstrap was true when setting up the integration.
-
hashDelimiter string
A delimiter used to separate key-value pairs.
`
`
hashKeyDelimiter string
A delimiter used to separate a key from its value.
:
-
arrayDelimiter string
A delimiter used to separate array elements.
,
-
port number
The port to use when connecting to your Databricks account host.
Optional
443
0-65535
workspaceUrl string
Databricks workspace URL. For example, my-workspace.cloud.databricks.com.
Required
-
-
httpPath string
The HTTP path of your Databricks cluster or SQL warehouse.
Required
-
-
authenticationType string
The type of authentication to use when connecting to Databricks.
Required
-
token
oAuthM2M
token string
The Databricks personal access token. This is the access token for the Immuta service principal.
Required if authenticationType is token.
-
-
proxyOptions object
This object allows you to configure your integration to use a proxy server. See the proxy options object description for child attributes.
Optional
[]
-
oAuthClientConfig object
This object represents your OAuth configuration. To use this authentication method, authenticationType must be oAuthM2M. See the oAuthClientConfig object description for parameters.
Required if you selected oAuthM2M as your authenticationType.
-
-
audit object
This object enables Databricks Unity Catalog query audit. See the audit object description for parameters.
Optional
Disabled by default. See the audit object description for parameters.
-
workspaceIds array[integer]
This array can be used to scope query audit to only ingest activity for specified workspaces.
Optional
[]
catalog string
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.
Optional
immuta
-
groupPattern object
This object allows you to exclude groups in Databricks from authorization checks. See the groupPattern object description for parameters.
Optional
[]
-
additionalWorkspaceConnections array[ object]
This object allows you to configure additional workspace connections for your integration. See the additionalWorkspaceConnections description for child attributes.
Optional
[]
-
workspaceUrl string
Databricks workspace URL. For example, my-workspace.cloud.databricks.com.
Required
-
-
httpPath string
The HTTP path of the compute for the workspace.
Required
-
-
authenticationType string
The type of authentication to use when connecting to Databricks. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace.
Required
-
token
oAuthM2M
token string
The Databricks personal access token. This is the access token for the Immuta service principal. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace.
Required if authenticationType is token.
-
-
oAuthClientConfig object
This object represents your OAuth configuration. To use this authentication method, authenticationType must be oAuthM2M. See the oAuthClientConfig object description for parameters. The additional workspace credentials will be used when processing objects in bound catalogs that are not accessible via the default workspace.
Required if you selected oAuthM2M as your authenticationType.
-
-
catalogs string
The name of the catalog to use for this additional workspace connection. The catalog name may only contain letters, numbers, and underscores and cannot start with a number. 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.
Required
-
-
enabled boolean
This setting enables or disables Databricks Unity Catalog query audit.
false
true or false
deny string
The name of a group in Databricks that will be excluded from having data policies applied. This account-level group should be used for privileged users and service accounts that require an unmasked view of data.
immuta_exemption_group
-
host string
The hostname of the proxy server.
Required
-
Valid URL hostnames
port number
The port to use when connecting to your proxy server.
Optional
443
0-65535
username string
The username to use with the proxy server.
Optional
[]
-
password string
The password to use with the proxy server.
Optional
[]
-
clientId string
The client identifier of the Immuta service principal you configured. This is the client ID displayed in Databricks when creating the client secret for the service principal.
Required
-
-
authorityUrl string
Authority URL of your identity provider.
Required
https://<your workspace name>.cloud.databricks.com/oidc/v1/token
-
scope
The scope limits the operations and roles allowed in Databricks by the access token. See the OAuth 2.0 documentation for details about scopes.
Optional
[]
-
clientSecret string
Required
-
-
role string
Google Cloud role used to connect to Google BigQuery.
Required
-
-
datasetSuffix string
Suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore.
Required
-
-
dataset string
Name of the BigQuery dataset to provision inside of the project for Immuta metadata storage.
Optional
immuta
-
location string
The dataset's location. After a dataset is created, the location can't be changed.
Required
-
Any valid GCP location (us-east1, for example).
credential string
The Google BigQuery service account JSON keyfile credential content. See the Google documentation for guidance on generating and downloading this keyfile.
Required
-
-
port number
The port to use when connecting to your BigQuery account host.
Optional
443
0-65535
host string
The URL of your Redshift account.
Required
-
Valid URL hostnames
database string
Name of a new empty database that the Immuta system user will manage and store metadata in.
Required
-
-
initialDatabase string
Name of the existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.
Required if autoBootstrap is true.
-
-
authenticationType string
The type of authentication to use when connecting to Redshift.
Required
-
userPassword
accessKey
okta
username string
The username of the system account that can act on Redshift objects and configure the integration.
Required if you selected userPassword as your authenticationType.
-
-
password string
The password of the system account that can act on Redshift objects and configure the integration.
Required if you selected userPassword as your authenticationType.
-
-
okta object
This object represents your Okta configuration. See the Okta object description for parameters.
Required if you selected okta as your authenticationType.
-
-
databaseUser string
The Redshift database username.
Required if you selected accessKey as your authenticationType.
-
-
accessKeyId string
The Redshift access key ID.
Required if you selected accessKey as your authenticationType.
-
-
secretKey string
The Redshift secret key.
Required if you selected accessKey as your authenticationType.
-
-
sessionToken string
The Redshift session token.
Optional if you selected accessKey as your authenticationType.
-
-
port number
The port to use when connecting to your Redshift account host.
Optional
5439
0-65535
impersonation object
Enables user impersonation. See the impersonation object description for parameters.
Optional
Disabled by default. See the impersonation object description for parameters.
-
connectArgs string
The connection string arguments to pass to the ODBC driver when connecting as the Immuta system user.
Optional
-
-
authenticationType string
The type of authentication used when originally configuring the Redshift integration.
Required if autoBootstrap was true when setting up the integration.
userPassword
accessKey
okta
username string
The username of the system account that configured the integration.
Required if you selected userPassword as your authenticationType.
-
password string
The password of the system account that configured the integration.
Required if you selected userPassword as your authenticationType.
-
databaseUser string
The Redshift database username.
Required if you selected accessKey as your authenticationType.
-
accessKeyId string
The Redshift access key ID.
Required if you selected accessKey as your authenticationType.
-
secretKey string
The Redshift secret key.
Required if you selected accessKey as your authenticationType.
-
sessionToken string
The Redshift session token.
Optional if you selected accessKey as your authenticationType.
-
okta object
This object represents your Okta configuration. See the Okta object description for parameters.
Required if you selected okta as your authenticationType.
-
enabled boolean
When true, enables user impersonation.
false
true or false
role string
The name of the user impersonation role.
immuta_impersonation
-
username string
The username of the system account that can act on Redshift objects and configure the integration.
Required
-
-
password string
The password of the system account that can act on Redshift objects and configure the integration.
Required
-
-
appId string
The Okta application ID.
Required
-
-
idpHost string
The Okta identity provider host URL.
Required
-
-
role string
The Okta role.
Required
-
-
host string
The URL of your Snowflake account.
Required
-
Valid URL hostnames
warehouse string
The default pool of compute resources the Immuta system user will use to run queries and perform other Snowflake operations.
Required
-
-
database string
Name of a new empty database that the Immuta system user will manage and store metadata in.
Required
-
-
authenticationType string
The type of authentication to use when connecting to Snowflake.
Required
-
userPassword
keyPair
oAuthClientCredentials
username string
The username of a Snowflake account that can act on Snowflake objects and configure the integration.
Required if you selected userPassword as your authenticationType.
-
-
password string
The password of a Snowflake account that can act on Snowflake objects and configure the integration.
Required if you selected userPassword as your authenticationType.
-
-
privateKey string
The private key. Replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
Required if you selected keyPair as your authenticationType.
-
-
oAuthClientConfig object
This object represents your OAuth configuration. To use this authentication method, autoBootstrap must be false. See the oAuthClientConfig object description for parameters.
Required if you selected oAuthClientCredentials as your authenticationType.
-
-
role string
The privileged Snowflake role used by the Immuta system account when configuring the Snowflake integration.
Required when autoBootstrap is true.
-
-
port number
The port to use when connecting to your Snowflake account host.
Optional
443
0-65535
audit object
This object enables Snowflake query audit. See the audit object description for the parameter.
Optional
Disabled by default. See the audit object description for the parameter.
-
impersonation object
Enables user impersonation. See the impersonation object description for parameters.
Optional
Disabled by default. See the impersonation object description for parameters.
-
userRolePattern object
This object excludes roles and users from authorization checks. See the userRolePattern object description for parameters.
Optional
{[]}
-
workspaces object
This object represents an Immuta project workspace configured for Snowflake. See the workspaces object description for parameters.
Optional
Disabled by default. See the workspaces object description for parameters.
-
connectArgs string
The connection string arguments to pass to the Node.js driver when connecting as the Immuta system user.
Optional
-
-
privilegedConnectArgs string
The connection string arguments to pass to the Node.js driver when connecting as the privileged user.
Optional when autoBootstrap is true.
-
-
lineage object
Enables Snowflake lineage ingestion so that Immuta can apply tags added to Snowflake tables to their descendant data source columns. See the native lineage ingestion object description for parameters.
Optional
-
-
enabled boolean
This setting enables or disables Snowflake query audit.
false
true or false
authenticationType string
The type of authentication used when originally configuring the integration.
Required if autoBootstrap was true when configuring the integration.
userPassword
keyPair
oAuthClientCredentials
username string
The username of the system account that configured the integration.
Required for the Azure Synapse Analytics integration or if you selected userPassword as your authenticationType for Redshift or Snowflake.
-
password string
The password of the system account that configured the integration.
Required for the Azure Synapse Analytics integration or if you selected userPassword as your authenticationType for Redshift or Snowflake.
-
privateKey string
The private key. Replace new lines in the private key with a backslash before the new line character: "\n". If you are using another means of configuration, such as a Python script, the "\n" should not be added.
Required if you selected keyPair as your authenticationType.
-
oAuthClientConfig object
This object represents your OAuth configuration. See the oAuthClientConfig object description for parameters.
Required if you selected oAuthClientCredentials as your authenticationType.
-
role string
The privileged Snowflake role used by the Immuta system account when configuring the Snowflake integration.
Required when autoBootstrap is true for Snowflake.
-
enabled boolean
When true, enables user impersonation.
false
true or false
role string
The name of the user impersonation role.
IMMUTA_IMPERSONATION
-
enabled boolean
When true, enables Snowflake native lineage so that Immuta can apply tags added to Snowflake data sources to their descendant data source columns in Immuta.
Optional
false
true or false
lineageConfig object
Configures what tables Immuta will ingest lineage history for, the number of rows to ingest per batch, and what tags to propagate. Child parameters include tableFilter, tagFilterRegex, and ingestBatchSize.
Required if enabled is true.
-
-
lineageConfig.tableFilter string
This child parameter of lineageConfig determines which tables Immuta will ingest lineage for. Use a regular expression that excludes / from the beginning and end to filter tables. Without this filter, Immuta will attempt to ingest lineage for every table on your Snowflake instance.
Optional
^.*$
Regular expression that excludes / from the beginning and end.
lineageConfig.tagFilterRegex string
This child parameter of lineageConfig determines which tags to propagate using lineage. Use a regular expression that excludes / from the beginning and end to filter tags. Without this filter, Immuta will ingest lineage for every tag on your Snowflake instance.
Optional
^.*$
Regular expression that excludes / from the beginning and end.
lineageConfig.ingestBatchSize number
This child parameter of lineageConfig configures the number of rows Immuta ingests per batch when streaming Access History data from your Snowflake instance.
Optional
1000
Minimum value of 1.
provider string
The identity provider for OAuth, such as Okta.
Required
-
-
clientId string
The client identifier of your registered application.
Required
-
-
authorityUrl string
Authority URL of your identity provider.
Required
-
-
useCertificate boolean
Specifies whether or not to use a certificate and private key for authenticating with OAuth.
Required
-
true or false
publicCertificateThumbprint string
Your certificate thumbprint.
Required if useCertificate is true.
-
-
oauthPrivateKey string
The private key content.
Required if useCertificate is true.
-
-
clientSecret string
Client secret of the application.
Required if useCertificate is false.
-
-
resource string
An optional resource to pass to the token provider.
Optional
-
-
scope string
The scope limits the operations and roles allowed in Snowflake by the access token. See the OAuth 2.0 documentation for details about scopes.
Optional
[]
-
exclude array[string]
This array is a list of roles and users to exclude from authorization checks.
[]
-
enabled boolean
This setting enables or disables Snowflake project workspaces. If you use Snowflake secure data sharing with Immuta, set this property to true, as project workspaces are required. If you use Snowflake table grants, set this property to false; project workspaces cannot be used when Snowflake table grants are enabled.
false
true or false
warehouses array[string]
This array is a list of warehouses workspace users have usage privileges on.
[]
-
id number
The unique identifier of the integration.
The status of the integration. Statuses include createError, creating, deleteError, deleting, editError, editing, enabled, migrateError, and migrating. See the statuses table below for descriptions.
The results of the validation tests. See the object description for details.
config object
The integration configuration. See the integration configuration payload for Amazon S3, Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake for details.
status string
Whether or not the connection validation passed.
passed
failed
warning
skipped
validationTests array[]
This array includes the validation tests run on the integration connection.
-
validationTests.name string
The name of the validation test.
See the section corresponding to your integration type for a list of test names and messages:
validationTests.status string
The status of the validation test.
passed
failed
warning
skipped
validationTests.message string
When a test fails, the message provides context and guidance for addressing the failure.
See the section corresponding to your integration type for a list of test names and messages:
The table below provides definitions for each status and the state of configured data platform integrations. The status of the integration appears on the integrations tab of the Immuta application settings page and in the response schema of the integrations API.
If any errors occur with the integration configuration, a banner will appear in the Immuta UI with guidance for remediating the error.
| Status | Description | State |
|---|---|---|
createError
Error occurred during creation of the integration.
creating
Integration is in the process of being created and set up.
deleted
Integration is deleted.
Not in use
deleteError
Error occurred while deleting the integration. The integration has been rolled back to the previous state.
deleting
Integration is in the process of being disabled or deleted.
disabled
Integration was force disabled and no cleanup was performed on the native platform.
Not in use
editError
Error occurred while editing the integration. The integration has been rolled back to the previous state.
editing
The integration is in the process of being edited.
enabled
The integration is enabled and active.
migrateError
Error occurred while performing a migration of the integration. The integration has been rolled back to the previous state.
migrating
Migration is being performed on the integration. An example of a migration is a stored procedure update.
recurringValidationError
Validation has failed during the periodic check and the integration may be misconfigured.