# 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](#snowflake-connection-object) or the [Databricks Unity Catalog connection object](#databricks-unity-catalog-host-payload). | Required | - |
| **settings** `object` | See [Settings object](#settings-object). | Optional | - |
| **options** `object` | See [Options object](#options-object). | Optional | - |
| **nativeIntegration** `object` | See [Native integration object](#snowflake-native-integration-object). | 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 | |
| **activateNewChildren** `boolean` | If `true`, all new children found during object sync will be registered as active. | Optional | |
| **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 | |
### 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 | |
| **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](#snowflake-config-object) or [Databricks Unity Catalog](#databricks-unity-catalog-config-object). | Required | - |
| **unityCatalog** `boolean` | When `true`, the integration is for Databricks Unity Catalog. | Required if **type** is `Databricks`. | `true` |
### Snowflake connection object
The **connection** object configures the Snowflake 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 | |
hostname string | The URL of your Snowflake account. This is the same as host. | Required | - |
port integer | The port to use when connecting to 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 connect to the host. Make sure this auth type is the same used when requesting the script. | Required | keyPairoAuthClientCredentialsuserPassword
|
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. | - |
### 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 connect to the host. Make sure this auth type is the same as the `config` object. | Required | keyPairoAuthClientCredentialsuserPassword
|
| **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](https://documentation.immuta.com/saas/~/changes/l3NnvynMHxi6VvqRtJhK/developer-guides/api-intro/enhanced-onboarding-api/host-connection-payloads-reference-guide#snowflake-oauth-object). | Required when **authenticationType** is `oAuthClientCredentials`. | - |
| **host** `string` | The URL of your Snowflake account. | Required | - |
| **port** `integer` | The port to use when connecting to 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](#snowflake-impersonation-object). | Optional | - |
| **audit** `object` | This object enables Snowflake query audit. See the [audit object](#audit-object). | Optional | - |
| **workspaces** `object` | This object represents an Immuta project workspace configured for Snowflake. See the [workspaces object](#snowflake-workspace-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](#snowflake-lineage-object). | Optional | - |
| **userRolePattern** `object` | This object excludes roles and users from authorization checks. See the user [role pattern object](#snowflake-user-role-pattern-object). | Optional | - |
### 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 | |
| **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.](#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.
| - |
## 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 | | |
hostname string | Your Databricks workspace URL. This is the same as host and workspaceURL. | Required | - | |
port integer | The port to use when connecting to 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 connect to 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 | - | |
## 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 connect to 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 connecting to 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](https://documentation.immuta.com/saas/~/changes/l3NnvynMHxi6VvqRtJhK/developer-guides/api-intro/enhanced-onboarding-api/host-connection-payloads-reference-guide#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](#databricks-group-pattern-object). | Optional | - |
| **jobConfig** `object` | This object controls query parsing configuration. See the [Databricks Unity Catalog job config object](#databricks-unity-catalog-job-config-object). | Optional | - |
## 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. | |
## 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 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` |