Host Registration Payloads Reference Guide

The parameters for configuring an integration in Immuta are outlined in the table below.

Attribute	Description	Required or optional	Accepted values
connectionKey string	A unique name for the host connection.	Required	-
connection object	See Snowflake connection object or the Databricks Unity Catalog connection object.	Required	-
settings object	See Settings object.	Optional	-
options object	See Options object.	Optional	-
nativeIntegration object	See Native integration object.	Required	-

Connection object

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

Snowflake connection object

Attribute	Description	Required or optional	Accepted values
technology string	The technology backing the new host.	Required	Snowflake Databricks
hostname string	The URL of your Snowflake account. This is the same as host.	Required	-
port integer	The port to use when registering your Snowflake account host. Defaults to 443.	Required	0-65535
warehouse string	The default pool of compute resources the Immuta system user will use to run queries and perform other Snowflake operations.	Required	-
role string	The privileged Snowflake role used by the Immuta system account when configuring the Snowflake host. It must be able to see the data that Immuta will govern.	Required	-
authenticationType string	The authentication type to register the host. Make sure this auth type is the same used when requesting the script.	Required	keyPair oAuthClientCredentials userPassword
username string	The username of the system account that can act on Snowflake objects and configure the host.	Required when authenticationType is keyPair or userPassword.	-
password string	The password of the system account that can act on Snowflake objects and configure the host.	Required when authenticationType is userPassword.	-
privateKeyPassword string	The Snowflake private key password.	Required when authenticationType is keyPair and the private key is encrypted.	-
privateKey object	See Snowflake private key object.	Required when authenticationType is keyPair.	-
oAuthClientConfig object	See Snowflake OAuth object.	Required when authenticationType is oAuthClientCredentials.	-

Databricks Unity Catalog connection object

The connection object configures the Databricks Unity Catalog connection information. The table below outlines its child parameters.

Attribute	Description	Required or optional	Accepted values
technology string	The technology backing the new host.	Required	Databricks Snowflake
hostname string	Your Databricks workspace URL. This is the same as host and workspaceURL.	Required	-
port integer	The port to use when registering your Databricks account host. Defaults to 443.	Required	0-65535
httpPath string	The HTTP path of your Databricks cluster or SQL warehouse.	Required	-
authenticationType string	The authentication type to register the host. Make sure this auth type is the same used when requesting the script.	Required	token
token string	The Databricks personal access token for the service principal created for Immuta.	Required	-

Settings object

The settings object configures connection settings. The table below outlines its child parameters.

Attribute	Description	Required or optional	Accepted values
isActive boolean	If true, data objects will be active by default when created in Immuta.	Optional	true false
activateNewChildren boolean	If true, all new children found during object sync will be registered as active.	Optional	true false
infrastructureAdmins array	A list of the users and groups that are infrastructure admins on the host. These users can crawl the host, edit the connection, and delete data objects.	Optional	-
dataOwners array	A list of users and groups that are data owners on the host. These users will be data owners for all the data sources under the data object they are assigned to.	Optional	-

Options object

The options object configures an option for your connection. The table below outlines its child parameter.

Attribute	Description	Required or optional	Accepted values
forceRecursiveCrawl boolean	When true, both active and inactive objects will be found by object sync.	Optional	true false

Native integration object

The nativeIntegration object configures integration information and options. The table below outlines its child parameters.

Attribute	Description	Required or optional	Accepted values
type string	The type of technology.	Required	Snowflake Databricks
autoBootstrap boolean	When false, you must set up your environment manually before configuring the host with the API.	Required	false
config object	This object specifies the integration settings. See the config object description for your technology: Snowflake or Databricks Unity Catalog.	Required	-
unityCatalog boolean	When true, the integration is for Databricks Unity Catalog.	Required if type is Databricks.	true

Snowflake config object

The config object configures the Snowflake integration information and options. The table below outlines its child parameters.

Attribute	Description	Required or optional	Accepted values
authenticationType string	The authentication type to register the host. Make sure this auth type is the same as the config object.	Required	keyPair oAuthClientCredentials userPassword
username string	The username of the system account that can act on Snowflake objects and configure the host.	Required when authenticationType is keyPair or userPassword.	-
password string	The password of the system account that can act on Snowflake objects and configure the host.	Required when authenticationType is userPassword.	-
privateKeyPassword string	The Snowflake private key password.	Required when authenticationType is keyPair and the private key is encrypted**.**	-
keyName string	The Immuta-given name of your private key.	Required when authenticationType is keyPair.	PRIV_KEY_FILE
userFilename string	The name of the private key file on your machine.	Required when authenticationType is keyPair.	-
content 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. In the integrations API, this is the config.privateKey attribute.	Required when authenticationType is keyPair.	-
oAuthClientConfig object	See Snowflake OAuth object.	Required when authenticationType is oAuthClientCredentials.	-
host string	The URL of your Snowflake account.	Required	-
port integer	The port to use when registering your Snowflake account host.	Optional. Defaults to 443.	0-65535
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	The name of the Snowflake database Immuta will create to store internal entitlements and other user data specific to Immuta. This database will only be readable for the Immuta user and should not be granted to other users. The database name may only contain letters, numbers, and underscores and cannot start with a number.	Required	-
impersonation object	Enables user impersonation. See the impersonation object.	Optional	-
audit object	This object enables Snowflake query audit. See the audit object.	Optional	-
workspaces object	This object represents an Immuta project workspace configured for Snowflake. See the workspaces object.	Optional	-
lineage object	Enables Snowflake lineage ingestion so that Immuta can apply tags added to Snowflake tables to their descendant data source columns. See the lineage object.	Optional	-
userRolePattern object	This object excludes roles and users from authorization checks. See the user role pattern object.	Optional	-

Databricks Unity Catalog config object

The config object configures the Databricks Unity Catalog integration information and options. The table below outlines its child parameters.

Attribute	Description	Required or optional	Accepted values
authenticationType string	The authentication type to register the host. Make sure this auth type is the same used when requesting the script.	Required	token
token string	The Databricks personal access token for the service principal created for Immuta.	Required	-
host string	Your Databricks workspace URL. This is the same as hostname and workspaceURL.	Required	-
port integer	The port to use when registering your Databricks account host. Defaults to 443.	Optional. Defaults to 443.	0-65535
httpPath string	The HTTP path of your Databricks cluster or SQL warehouse.	Required	-
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.	Required	-
audit object	This object enables Databricks Unity Catalog query audit. See the audit object.	Optional	-
workspaceIds array	The optional workspaces to filter audit to.	Optional	-
enableNativeQueryParsing boolean	If true, native query parsing is enabled.	Optional	false
groupPattern object	Excludes the listed group from having data policies applied in the Databricks Unity Catalog integration. See the Databricks Unity Catalog group pattern object.	Optional	-
jobConfig object	This object controls query parsing configuration. See the Databricks Unity Catalog job config object.	Optional	-

Snowflake specific objects

Snowflake private key object

The privateKey object represents your private key in Snowflake. This object is required if you set privateKey as your authentication type. The table below outlines the object's child parameters

Attribute	Description	Accepted values
keyName string	The Immuta-given name of your private key.	PRIV_KEY_FILE
userFilename string	The name of the private key file on your machine.	-
content 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. In the integrations API, this is the config.privateKey attribute.	-

Snowflake OAuth object

The oAuthClientConfig object represents your OAuth configuration in Snowflake. This object is required if you set oAuthClientCredentials as your authentication type. The table below outlines the object's child parameters

Attribute	Description	Required or optional	Accepted values
useCertificate boolean	Specifies whether or not to use a certificate and private key for authenticating with OAuth.	Required	true false
clientId string	The client identifier of your registered application.	Required	-
authorityUrl string	Authority URL of your identity provider.	Required	-
scope string	The scope limits the operations and roles allowed in Snowflake by the access token.	Required	session:role-any
resource string	An optional resource to pass to the token provider.	Optional	-
publicCertificateThumbprint string	Your certificate thumbprint.	Required if useCertificate is true.	-
oauthPrivateKey object	See Snowflake OAuth with certificate/private key.	Required if useCertificate is true.	-
clientSecret string	Client secret of the application.	Required if useCertificate is false.	-

Snowflake OAuth private key

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

Attribute	Description	Accepted values
keyName string	The Immuta-given name of your private key.	oauth client certificate
userFilename string	The name of your private key file on your machine.	-
content 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. In the integrations API, this is the config.oauthPrivateKey attribute.	-

Snowflake impersonation object

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

Parameter	Description	Accepted values
enabled boolean	When true, enables user impersonation.	true or false
role string	The name of the user impersonation role.	-

Snowflake workspace object

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

Parameter	Description	Accepted values
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.	true or false
warehouses array[string]	This array is a list of warehouses workspace users have usage privileges on.	-

Snowflake lineage object

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.

Parameter	Description	Required or optional	Accepted values
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	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	Minimum value of 1.

Snowflake user role pattern object

The userRolePattern object excludes roles and users from authorization checks in the Snowflake integration. The table below outlines its child parameter.

Parameter	Description	Accepted values
exclude array[string]	This array is a list of roles and users to exclude from authorization checks.	-

Databricks Unity Catalog specific objects

Databricks group pattern object

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 parameter.

Parameter	Description	Default values	Accepted values
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	-

Databricks Unity Catalog job config object

The jobConfig object controls configuration settings for Databricks Unity Catalog query parsing. The table below outlines its child parameters.

Attribute	Description	Accepted values
workspaceDirectoryPath string	The file path of the workspace directory.	/Workspace/ImmutaArtifacts
jobClusterId string	The ID of the job cluster.	undefined

Audit object

The audit object enables query audit. The table below outlines its child parameter.

Attribute	Description	Accepted values
enabled boolean	If true, query audit is enabled. Set to true for the recommended configuration.	true false