> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/2024.2/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/2024.2/developer-guides/api-intro/integrations-api/reference-guides/integrations-api.md). # Integrations API Endpoints 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. ## Endpoints | Method | Endpoint | Description | | ---------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **GET** | [`/integrations`](#get-integrations) | Gets all integration configurations | | **POST** | [`/integrations`](#post-integrations) | Creates an integration | | **DELETE** | [`/integrations/{id}`](#delete-integrationsid) | Deletes a configured integration | | **GET** | [`/integrations/{id}`](#get-integrationsid) | Gets an integration configuration | | **PUT** | [`/integrations/{id}`](#put-integrationsid) | Updates a configured integration | | **GET** | [`/integrations/{id}/status`](#get-integrationsidstatus) | Gets the status of the specified integration | | **POST** | [`/integrations/scripts/cleanup`](#post-integrationsscriptscleanup) | Creates a script to remove Immuta-managed resources from your platform for integrations that were not successfully created | | **POST** | [`/integrations/scripts/create`](#post-integrationsscriptscreate) | Creates a script to set up Immuta-managed resources in your platform | | **POST** | [`/integrations/{id}/scripts/delete`](#post-integrationsidscriptsdelete) | Creates a script to remove Immuta-managed resources from your platform for integrations that were successfully configured | | **POST** | [`/integrations/{id}/scripts/edit`](#post-integrationsidscriptsedit) | Creates a script to edit existing Immuta-managed resources in your platform | | **POST** | [`/integrations/scripts/initial-create`](#post-integrationsscriptsinitial-create) | Creates the first script to set up Immuta-managed resources in your Azure Synapse Analytics or Redshift platform | | **POST** | [`/integrations/scripts/post-cleanup`](#post-integrationsscriptspost-cleanup) | Creates the second script to remove Immuta-managed resources from your Azure Synapse Analytics integration if it was not successfully created | ## GET /integrations Gets all integration configurations. ```shell curl -X 'GET' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' ``` ### Response The response returns the configuration for all integrations. See the [response schema reference](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/response-schema.md) 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/status-codes.md#get-error) for a list of statuses, error messages, and troubleshooting guidance. ```json [ { "id": "1", "status": "enabled", "validationResults": { "status": "passed", "validationTests": [ { "name": "Initial Validation: Basic Connection Test", "status": "passed" }, { "name": "Initial Validation: Default Warehouse Access Test", "status": "passed", "result": [] }, { "name": "Initial Validation: Validate access to Privileged Role", "status": "passed", "result": [] }, { "name": "Validate Automatic: Database Does Not Exist", "status": "passed" }, { "name": "Validate Automatic: Impersonation Role Does Not Exist", "status": "skipped" }, { "name": "Validate Automatic Bootstrap User Grants", "status": "passed" } ] }, "type": "Snowflake", "autoBootstrap": true, "config": { "host": "organization.us-east-1.snowflakecomputing.com", "warehouse": "SAMPLE_WAREHOUSE", "database": "SNOWFLAKE_SAMPLE_DATA", "port": 443, "audit": { "enabled": false }, "workspaces": { "enabled": false }, "impersonation": { "enabled": false }, "lineage": { "enabled": false }, "authenticationType": "userPassword", "username": "", "password": "", "role": "ACCOUNTADMIN" }, { "id": "2", "status": "enabled", "type": "Databricks", "validationResults": { "status": "passed", "validationTests": [ { "name": "Metastore validation", "status": "passed" }, { "name": "Basic Connection Test", "result": [ { "1": 1 } ], "status": "passed" } ] }, "autoBootstrap": true, "config": { "workspaceUrl": "www.example-workspace.cloud.databricks.com", "httpPath": "sql/protocolv1/o/0/0000-00000-abc123", "authenticationType": "token", "token": "REDACTED", "audit": { "enabled": false }, "catalog": "immuta" } } } ] ``` ## POST /integrations Creates an integration configuration that allows Immuta to manage access policies on data registered in Immuta. ### Amazon S3 example 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Native S3", "autoBootstrap": false, "config": { "name": "S3 integration", "awsAccountId": "123456789", "awsRegion": "us-east-1", "awsLocationRole": "arn:aws:iam::123456789:role/access-grants-instance-role", "awsLocationPath": "s3://", "authenticationType": "accessKey", "awsAccessKeyId": "123456789", "awsSecretAccessKey": "123456789" } }' ``` ### Azure Synapse Analytics example 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Azure Synapse Analytics", "autoBootstrap": true, "config": { "host": "organization.azure.com", "schema": "sample_schema", "database": "immuta", "metadataDelimiters": { "hashDelimiter": "|", "hashKeyDelimiter": "-", "arrayDelimiter": "," }, "username": "taylor@synapse.com", "password": "abc1234", "authenticationType": "userPassword" } }' ``` ### Databricks Unity Catalog example This request creates a Databricks Unity Catalog integration configuration that allows Immuta to administer Unity Catalog policies on data registered in Immuta. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Databricks", "autoBootstrap": true, "config": { "workspaceUrl": "www.example-workspace.cloud.databricks.com", "httpPath": "sql/protocolv1/o/0/0000-00000-abc123", "authenticationType": "token", "token": "REDACTED", "catalog": "immuta" } }' ``` ### Google BigQuery example 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Google BigQuery", "autoBootstrap": false, "config": { "role": "immuta", "datasetSuffix": "_secureView", "dataset": "immuta", "location": "us-east1", "credential": "{\"type\":\"service_account\",\"project_id\":\"innate-conquest-123456\",\"private_key_id\":\"9163c12345690924f5dd218ff39\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\nXXXXXXXro0s\n/yQlPQijowkccmrmWJyr93kdLnwJzBvLHCto/+W\ncvF2ygX9oM/dyUK//z//4nptMp+Ck//Yw3D4rIBwGu4DWiR1qRnf\nDoGyXfThPTQ==\n-----END PRIVATE KEY-----\n\",\"client_email\":\"service-account-id@innate-conquest-123456.iam.gserviceaccount.com\",\"client_id\":\"1166290***432952487857\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"https://www.googleapis.com/robot/v1/metadata/x509/service-account-id%40innate-conquest-123456.iam.gserviceaccount.com\",\"universe_domain\":\"googleapis.com\"}" } }' ``` ### Redshift example 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Redshift", "autoBootstrap": true, "config": { "host": "organization.aws.amazon.com", "database": "immuta", "initialDatabase": "REDSHIFT_SAMPLE_DATA", "authenticationType": "userPassword", "username": "taylor@redshift.com", "password": "abc1234" } }' ``` ### Snowflake example 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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md#requirements). These credentials are not stored; they are used by Immuta to configure the integration. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Snowflake", "autoBootstrap": true, "config": { "host": "organization.us-east-1.snowflakecomputing.com", "warehouse": "SAMPLE_WAREHOUSE", "database": "SNOWFLAKE_SAMPLE_DATA", "authenticationType": "userPassword", "username": "taylor@snowflake.com", "password": "abc1234", "role": "ACCOUNTADMIN" } }' ``` ### Starburst (Trino) example 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Trino" }' ``` ### Body parameters The request accepts a JSON or YAML payload with the parameters outlined below. | Parameter | Description | Required or optional | Default values | Accepted values | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md), [Databricks Unity Catalog](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/databricks-uc-api.md), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md), [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md). | 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#amazon-s3-configuration-object), [Azure Synapse Analytics](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#azure-synapse-analytics-configuration-objects), [Databricks Unity Catalog](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#databricks-unity-catalog-configuration-objects), [Google BigQuery](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#google-bigquery-configuration-object), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#redshift-configuration-objects), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#snowflake-configuration-objects). | Required for all integrations except Starburst (Trino) | - | - | ### Query parameter | Parameter | Description | Required or optional | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **dryRun** `boolean` | When `true`, the integration configuration will not actually be created, and the response returns the validation tests statuses. | Optional | ### Response The response returns the status of the integration configuration connection. See the [response schema reference](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/response-schema.md) for details about the response schema. {% tabs %} {% tab title="200 response" %} A successful response includes the validation tests statuses. ```json { "id": "123456789", "status": "creating", "validationResults": { "status": "passed", "validationTests": [ { "name": "Initial Validation: Basic Connection Test", "status": "passed" }, { "name": "Initial Validation: Default Warehouse Access Test", "status": "passed", "result": [] }, { "name": "Initial Validation: Validate access to Privileged Role", "status": "passed", "result": [] }, { "name": "Validate Automatic: Database Does Not Exist", "status": "passed" }, { "name": "Validate Automatic: Impersonation Role Does Not Exist", "status": "skipped" }, { "name": "Validate Automatic Bootstrap User Grants", "status": "passed" } ] } } ``` {% endtab %} {% tab title="Unsuccessful request" %} An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/status-codes.md#post-errors) for a list of statuses, error messages, and troubleshooting guidance. ```json { "statusCode": 409, "error": "Conflict", "message": "Snowflake integration already exists on host organization.us-east-1.snowflakecomputing.com (id = 123456789)" } ``` {% endtab %} {% endtabs %} ## DELETE /integrations/{id} Deletes the integration configuration you specify in the request. ```shell curl -X 'DELETE' \ 'https://www.organization.immuta.com/integrations/123456789' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "authenticationType": "userPassword", "username": "taylor@snowflake.com", "password": "abc1234", "role": "ACCOUNTADMIN" }' ``` ### Request parameter | Parameter | Description | Required or optional | | --------------- | ------------------------------------------------------- | -------------------- | | **id** `number` | The unique identifier of the integration configuration. | Required | ### Query parameter | Parameter | Description | Required or optional | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **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 | ### Body parameters 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: * [Delete Azure Synapse Analytics integration payload](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#delete-azure-synapse-analytics-payload) * [Delete Redshift integration payload](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#delete-redshift-integration-payload) * [Delete Snowflake integration payload](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#delete-snowflake-integration-payload) ### Response The response returns the status of the integration configuration that has been deleted. See the [response schema reference](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/response-schema.md) 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/status-codes.md#delete-errors) for a list of statuses, error messages, and troubleshooting guidance. ```json { "id": "123456789", "status": "deleting", "validationResults": { "status": "passed", "validationTests": [ { "name": "Initial Validation: Basic Connection Test", "status": "passed" }, { "name": "Initial Validation: Default Warehouse Access Test", "status": "passed", "result": [] }, { "name": "Initial Validation: Validate access to Privileged Role", "status": "passed", "result": [] }, { "name": "Validate Automatic: Database Does Not Exist", "status": "passed" }, { "name": "Validate Automatic: Impersonation Role Does Not Exist", "status": "skipped" }, { "name": "Validate Automatic Bootstrap User Grants", "status": "passed" } ] } } ``` ## GET /integrations/{id} Gets the integration configuration you specify in the request. ```shell curl -X 'GET' \ 'https://www.organization.immuta.com/integrations/123456789' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' ``` ### Request parameter | Parameter | Description | Required or optional | | --------------- | ------------------------------------------------------- | -------------------- | | **id** `number` | The unique identifier of the integration configuration. | Required | ### Response The response returns an integration configuration. See the [response schema reference](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/response-schema.md) 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/status-codes.md#get-error) for a list of statuses, error messages, and troubleshooting guidance. ```json { "id": "123456789", "status": "enabled", "validationResults": { "status": "passed", "validationTests": [ { "name": "Initial Validation: Basic Connection Test", "status": "passed" }, { "name": "Initial Validation: Default Warehouse Access Test", "result": [], "status": "passed" }, { "name": "Initial Validation: Table Grants Role Prefix is Unique", "status": "passed" }, { "name": "Initial Validation: Validate access to Privileged Role", "result": [], "status": "passed" }, { "name": "Validate Automatic: Database Does Not Exist", "status": "passed" }, { "name": "Validate Automatic: Impersonation Role Does Not Exist", "status": "skipped" }, { "name": "Validate Automatic Bootstrap User Grants", "status": "passed" }] }, "type": "Snowflake", "autoBootstrap": true, "config": { "host": "organization.us-east-1.snowflakecomputing.com", "warehouse": "SAMPLE_WAREHOUSE", "database": "SNOWFLAKE_SAMPLE_DATA", "port": 443, "audit": { "enabled": false }, "workspaces": { "enabled": false }, "impersonation": { "enabled": false }, "lineage": { "enabled": false }, "authenticationType": "userPassword", "username": "", "password": "", "role": "ACCOUNTADMIN" } } ``` ## PUT /integrations/{id} Updates an existing integration configuration. ### Azure Synapse Analytics example This request enables user impersonation for the Azure Synapse Analytics integration. ```shell curl -X 'PUT' \ 'https://www.organization.immuta.com/integrations/123456789' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Azure Synapse Analytics", "autoBootstrap": true, "config": { "host": "organization.azure.com", "schema": "sample_schema", "database": "immuta", "impersonation": { "enabled": true, "role": "IMMUTA_IMPERSONATION" }, "metadataDelimiters": { "hashDelimiter": "|", "hashKeyDelimiter": "-", "arrayDelimiter": "," }, "username": "taylor@synapse.com", "password": "abc1234", "authenticationType": "userPassword" } }' ``` ### Databricks Unity Catalog example The request below updates the access token. ```shell curl -X 'PUT' \ 'https://www.organization.immuta.com/integrations/123456789' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Databricks", "autoBootstrap": true, "config": { "workspaceUrl": "www.example-workspace.cloud.databricks.com", "httpPath": "sql/protocolv1/o/0/0000-00000-abc123", "authenticationType": "token", "token": "REDACTED", "catalog": "immuta" } }' ``` ### Google BigQuery example The request below updates the private key for the Google BigQuery integration. ```shell curl -X 'PUT' \ 'https://www.organization.immuta.com/integrations/{id}' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Google BigQuery", "autoBootstrap": false, "config": { "role": "immuta", "datasetSuffix": "_secureView", "dataset": "immuta", "location": "us-east1", "credential": "{\"type\":\"service_account\",\"project_id\":\"innate-conquest-123456\",\"private_key_id\":\"9163c12345690924f5dd218ff39\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\nXXXXXXXro0s\n/yQlPQijowkccmrmWJyr93kdLnwJzBvLHCto/+W\ncvF2ygX9oM/dyUK//z//4nptMp+Ck//Yw3D4rIBwGu4DWiR1qRnf\nDoGyXfThPTQ==\n-----END PRIVATE KEY-----\n\",\"client_email\":\"service-account-id@innate-conquest-123456.iam.gserviceaccount.com\",\"client_id\":\"1166290***432952487857\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"https://www.googleapis.com/robot/v1/metadata/x509/service-account-id%40innate-conquest-123456.iam.gserviceaccount.com\",\"universe_domain\":\"googleapis.com\"}" } }' ``` ### Redshift example This request enables user impersonation for the Redshift integration. ```shell curl -X 'PUT' \ 'https://www.organization.immuta.com/integrations/123456789' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Redshift", "autoBootstrap": true, "config": { "host": "organization.aws.amazon.com", "database": "immuta", "initialDatabase": "REDSHIFT_SAMPLE_DATA", "impersonation": { "enabled": true, "role": "immuta_impersonation" }, "authenticationType": "okta", "okta": { "username": "taylor@redshift.com", "password": "abc1234", "appId": "Okta", "idpHost": "organization.okta.com", "role": "admin" } } }' ``` ### Snowflake example This request enables auditing queries run in Snowflake. ```shell curl -X 'PUT' \ 'https://www.organization.immuta.com/integrations/123456789' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Snowflake", "autoBootstrap": true, "config": { "host": "organization.us-east-1.snowflakecomputing.com", "warehouse": "SAMPLE_WAREHOUSE", "database": "SNOWFLAKE_SAMPLE_DATA", "audit": { "enabled": true }, "authenticationType": "userPassword", "username": "taylor@snowflake.com", "password": "abc1234", "role": "ACCOUNTADMIN" } }' ``` ### Body parameters The request accepts a JSON or YAML payload with the parameters outlined below. | Parameter | Description | Required or optional | Default values | Accepted values | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md), [Databricks Unity Catalog](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/databricks-uc-api.md), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md), [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md). | 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#azure-synapse-analytics-configuration-objects), [Databricks Unity Catalog](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#databricks-unity-catalog-configuration-objects), [Google BigQuery](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#google-bigquery-configuration-object), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#redshift-configuration-objects), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#snowflake-configuration-objects). | Required | - | - | ### Query parameter | Parameter | Description | Required or optional | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **dryRun** `boolean` | When `true`, the integration configuration will not actually be updated, and the response returns the validation tests statuses. | Optional | ### Response The response returns the status of the integration configuration connection. See the [response schema reference](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/response-schema.md) for details about the response schema. {% tabs %} {% tab title="200 response" %} A successful response includes the validation tests statuses. ```json { "id": "123456789", "status": "editing", "validationResults": { "status": "passed", "validationTests": [ { "name": "Initial Validation: Basic Connection Test", "status": "passed" }, { "name": "Initial Validation: Default Warehouse Access Test", "status": "passed", "result": [] }, { "name": "Initial Validation: Validate access to Privileged Role", "status": "passed", "result": [] }, { "name": "Validate Automatic: Database Does Not Exist", "status": "passed" }, { "name": "Validate Automatic: Impersonation Role Does Not Exist", "status": "skipped" }, { "name": "Validate Automatic Bootstrap User Grants", "status": "passed" } ] } } ``` {% endtab %} {% tab title="Unsuccessful request" %} An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/status-codes.md#put-errors) for a list of statuses, error messages, and troubleshooting guidance. ```json { "statusCode": 409, "error": "Conflict", "message": "Unable to edit integration with ID 123456789 in current state editing." } ``` {% endtab %} {% endtabs %} ## GET /integrations/{id}/status Gets the status of the integration specified in the request. ```shell curl -X 'GET' \ 'https://www.organization.immuta.com/integrations/123456789/status' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' ``` ### Request parameter | Parameter | Description | Required or optional | | --------------- | ------------------------------------------------------- | -------------------- | | **id** `number` | The unique identifier of the integration configuration. | Required | ### Response The response returns the [status](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/response-schema.md#integration-statuses) of the specified integration. An unsuccessful request returns the HTTP status code and an error message. See the [HTTP status codes and error messages](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/status-codes.md#get-error) for a list of statuses, error messages, and troubleshooting guidance. ```json {"id":123456789,"status":"enabled"} ``` ## POST /integrations/scripts/cleanup 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](#post-integrationsscriptspost-cleanup) to create another script that will finish removing Immuta-managed resources from the platform. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations/scripts/cleanup' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Snowflake", "autoBootstrap": false, "config": { "host": "organization.us-east-1.snowflakecomputing.com", "warehouse": "SAMPLE_WAREHOUSE", "database": "SNOWFLAKE_SAMPLE_DATA", "audit": { "enabled": true }, "workspaces": { "enabled": false }, "impersonation": { "enabled": false }, "authenticationType": "userPassword", "username": "IMMUTA_SYSTEM_ACCOUNT", "password": "abc1234" } }' ``` ### Body parameters The request accepts a JSON or YAML payload with the parameters outlined below. | Parameter | Description | Required or optional | Default values | Accepted values | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------- | | **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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#delete-an-integration), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md#delete-an-integration), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md#delete-an-integration) 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#azure-synapse-analytics-configuration-objects), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#redshift-configuration-objects), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#snowflake-configuration-objects). | Required | - | - | ### Response 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: * [Delete Redshift integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md#delete-an-integration) * [Delete Snowflake integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md#delete-an-integration) * use the [/integrations/scripts/post-cleanup endpoint](#post-integrationsscriptspost-cleanup) to create another script that will finish removing Immuta-managed resources from your Azure Synapse Analytics platform. ## POST /integrations/scripts/create 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations/scripts/create' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Snowflake", "autoBootstrap": false, "config": { "host": "organization.us-east-1.snowflakecomputing.com", "warehouse": "SAMPLE_WAREHOUSE", "database": "SNOWFLAKE_SAMPLE_DATA", "audit": { "enabled": false }, "workspaces": { "enabled": false }, "impersonation": { "enabled": false }, "authenticationType": "userPassword", "username": "IMMUTA_SYSTEM_ACCOUNT", "password": "abc1234" } }' ``` ### Body parameters The request accepts a JSON or YAML payload with the parameters outlined below. | Parameter | Description | Required or optional | Default values | Accepted values | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#manual-setup), [Databricks Unity Catalog](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/databricks-uc-api.md#manual-setup), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md#manual-setup), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md#manual-setup) 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#azure-synapse-analytics-configuration-objects), [Databricks Unity Catalog](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#databricks-unity-catalog-configuration-objects), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#redshift-configuration-objects), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#snowflake-configuration-objects). | Required | - | - | ### Response The response returns the script that you will run in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment. ## POST /integrations/{id}/scripts/delete 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations/1/scripts/delete' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' ``` ### Response 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: * [Delete Azure Synapse Analytics integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#delete-an-integration) * [Delete Redshift integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md#delete-an-integration) * [Delete Snowflake integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md#delete-an-integration) ## POST /integrations/{id}/scripts/edit 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, Redshift, and Snowflake integrations. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations/1/scripts/edit' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Snowflake", "autoBootstrap": false, "config": { "host": "organization.us-east-1.snowflakecomputing.com", "warehouse": "SAMPLE_WAREHOUSE", "database": "SNOWFLAKE_SAMPLE_DATA", "audit": { "enabled": true }, "workspaces": { "enabled": false }, "impersonation": { "enabled": false }, "authenticationType": "userPassword", "username": "IMMUTA_SYSTEM_ACCOUNT", "password": "abc1234" } }' ``` ### Body parameters The request accepts a JSON or YAML payload with the parameters outlined below. | Parameter | Description | Required or optional | Default values | Accepted values | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#manual-update), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md#manual-update), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md#manual-update) 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#azure-synapse-analytics-configuration-objects), [Redshift](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#redshift-configuration-objects), or [Snowflake](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#snowflake-configuration-objects). | Required | - | - | ### Response 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: * [Configure Azure Synapse Analytics integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#update-an-integration-configuration) * [Configure Redshift integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md#update-an-integration-configuration) * [Configure Snowflake integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md#update-an-integration-configuration) ## POST /integrations/scripts/initial-create 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. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations/scripts/initial-create' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Azure Synapse Analytics", "autoBootstrap": false, "config": { "host": "organization.azure.com", "schema": "sample_schema", "database": "immuta", "metadataDelimiters": { "hashDelimiter": "|", "hashKeyDelimiter": "-", "arrayDelimiter": "," }, "username": "taylor@synapse.com", "password": "abc1234", "authenticationType": "userPassword" } }' ``` ### Body parameters The request accepts a JSON or YAML payload with the parameters outlined below. | Parameter | Description | Required or optional | Default values | Accepted values | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | ------------------------------------------------------------------------------------ | | **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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#manual-setup) or [Redshift](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md#manual-setup) 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](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#azure-synapse-analytics-configuration-objects) or [Redshift](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#redshift-configuration-objects) integration configuration for details. | Required | - | - | ### Response 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](#post-integrationsscriptscreate) to generate a script to finish creating the Immuta-managed resources in your platform. ## POST /integrations/scripts/post-cleanup 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](#post-integrationsscriptscleanup) to create the first script that will remove the initial Immuta-managed resources from the platform. ```shell curl -X 'POST' \ 'https://www.organization.immuta.com/integrations/scripts/post-cleanup' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \ -d '{ "type": "Azure Synapse Analytics", "autoBootstrap": false, "config": { "host": "organization.azure.com", "schema": "sample_schema", "database": "immuta", "metadataDelimiters": { "hashDelimiter": "|", "hashKeyDelimiter": "-", "arrayDelimiter": "," }, "username": "taylor@synapse.com", "password": "abc1234", "authenticationType": "userPassword" } }' ``` ### Body parameters The request accepts a JSON or YAML payload with the parameters outlined below. | Parameter | Description | Required or optional | Default values | Accepted values | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | -------------- | ------------------------- | | **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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#delete-an-integration) manual setup section for details. | Required | - | `false` | | **config** `object` | This object specifies the integration settings. See the **config** object description of [Azure Synapse Analytics](/2024.2/developer-guides/api-intro/integrations-api/reference-guides/payload.md#azure-synapse-analytics-configuration-objects) for details. | Required | - | - | ### Response 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](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md#delete-an-integration) instructions. ## Related guides See the following how-to guides for configuration examples and steps for creating, managing, or deleting your integration: * [Configure an Amazon S3 integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/s3-api.md) * [Configure an Azure Synapse Analytics integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/synapse-api.md) * [Configure a Databricks Unity Catalog integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/databricks-uc-api.md) * [Configure a Google BigQuery integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/bigquery-api.md) * [Configure a Redshift integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/redshift-api.md) * [Configure a Snowflake integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/snowflake-api.md) * [Configure a Starburst (Trino) integration](/2024.2/developer-guides/api-intro/integrations-api/how-to-guides/trino-api.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.immuta.com/2024.2/developer-guides/api-intro/integrations-api/reference-guides/integrations-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.