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

Gets all integration configurations

POST

Creates an integration

DELETE

Deletes a configured integration

GET

Gets an integration configuration

PUT

Updates a configured integration

POST

Regenerates an Immuta API key for the configured integration

GET

Gets the status of the specified integration

POST

Creates a script to remove Immuta-managed resources from your platform for integrations that were not successfully created

POST

Creates a script to set up Immuta-managed resources in your platform

POST

Creates a script to remove Immuta-managed resources from your platform for integrations that were successfully configured

POST

Creates a script to edit existing Immuta-managed resources in your platform

POST

Creates the first script to set up Immuta-managed resources in your Azure Synapse Analytics or Redshift platform

POST

Creates the second script to remove Immuta-managed resources from your Azure Synapse Analytics integration if it was not successfully created

GET /integrations

Gets all integration configurations.

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 for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

[
  {
    "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": "<REDACTED>",
      "password": "<REDACTED>",
      "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.

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.

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.

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.

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

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. These credentials are not stored; they are used by Immuta to configure the integration.

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.

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

Azure Synapse Analytics
Databricks
Google BigQuery
Native S3
Redshift
Snowflake
Trino

autoBootstrap boolean

When true, Immuta will automatically configure the integration in your Azure Synapse Analytics, Databricks Unity Catalog, Redshift, or Snowflake environment for you. When false, you must set up your environment manually before configuring the integration with the API. This parameter must be set to false in the Amazon S3 and Google BigQuery configurations. See the specific how-to guide for configuring your integration for details: , , , .

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: , , , , , or .

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 for details about the response schema.

A successful response includes the validation tests statuses.

{
  "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"
    }
    ]
  }
}

An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Snowflake integration already exists on host organization.us-east-1.snowflakecomputing.com (id = 123456789)"
}

DELETE /integrations/{id}

Deletes the integration configuration you specify in the request.

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:

Response

The response returns the status of the integration configuration that has been deleted. See the response schema reference for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "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.

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 for details about the response schema. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "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": "<REDACTED>",
    "password": "<REDACTED>",
    "role": "ACCOUNTADMIN"
  }
}

PUT /integrations/{id}

Updates an existing integration configuration.

Amazon S3 example

This request changes the name of the integration.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/123456789' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Native S3",
    "autoBootstrap": false,
    "config": {
      "name": "S3 integration edited",
      "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

This request enables user impersonation for the Azure Synapse Analytics integration.

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

This request updates the access token.

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",
      "groupPattern": {
        "deny": "admins"
      },
      "catalog": "immuta"
    }
    }'

Google BigQuery example

This request updates the private key for the Google BigQuery integration.

  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-accound-id%40innate-conquest-123456.iam.gserviceaccount.com\",\"universe_domain\":\"googleapis.com\"}"
    }
    }'

Redshift example

This request enables user impersonation for the Redshift integration.

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.

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: , , , .

Required

true or false

config object

This object specifies the integration settings. See the config object description for your integration for details: , , , , or .

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 for details about the response schema.

A successful response includes the validation tests statuses.

{
  "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"
    }
    ]
  }
}

An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Unable to edit integration with ID 123456789 in current state editing."
}

POST /integrations/{id}/regenerate

Regenerates an Immuta API key for the configured integration.

Starburst (Trino) example

This request regenerates an Immuta API key for the configured Starburst (Trino) integration. Once you make this request, your old Immuta API key will be deleted and will no longer be valid. See the Configure a Starburst (Trino) integration page for instructions on updating your Starburst (Trino) integration to use the new API key.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/123456789/regenerate' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

Response

The response returns the new Immuta API key. An unsuccessful request returns the status code and an error message. See the HTTP status codes and error messages page for a list of statuses, error messages, and troubleshooting guidance.

{ "newKey": "5bb6cae9******300c21acbb" }

GET /integrations/{id}/status

Gets the status of the integration specified in the request.

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 of the specified integration. An unsuccessful request returns the HTTP status code and an error message. See the HTTP status codes and error messages for a list of statuses, error messages, and troubleshooting guidance.

{"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 to create another script that will finish removing Immuta-managed resources from the platform.

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 , , or 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: , , or .

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
- Delete Snowflake integration
use the /integrations/scripts/post-cleanup endpoint 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.

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 , , , or 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: , , , or .

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.

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:

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, Databricks Unity Catalog, Redshift, and Snowflake integrations.

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

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: , , , or .

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:

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.

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

Required

false

config object

This object specifies the integration settings. See the config object description of the or 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 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 to create the first script that will remove the initial Immuta-managed resources from the platform.

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 manual setup section for details.

Required

false

config object

This object specifies the integration settings. See the config object description of 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 instructions.

See the following how-to guides for configuration examples and steps for creating, managing, or deleting your integration:

Integrations API Endpoints

Endpoints

GET /integrations

Response

POST /integrations

Amazon S3 example

Azure Synapse Analytics example

Databricks Unity Catalog example

Google BigQuery example

Redshift example

Snowflake example

Starburst (Trino) example

Body parameters

Query parameter

Response

DELETE /integrations/{id}

Request parameter

Query parameter

Body parameters

Response

GET /integrations/{id}

Request parameter

Response

PUT /integrations/{id}

Amazon S3 example

Azure Synapse Analytics example

Databricks Unity Catalog example

Google BigQuery example

Redshift example

Snowflake example

Body parameters

Query parameter

Response

POST /integrations/{id}/regenerate

Starburst (Trino) example

Response

GET /integrations/{id}/status

Request parameter

Response

POST /integrations/scripts/cleanup

Body parameters

Response

POST /integrations/scripts/create

Body parameters

Response

POST /integrations/{id}/scripts/delete

Response

POST /integrations/{id}/scripts/edit

Body parameters

Response

POST /integrations/scripts/initial-create

Body parameters

Response

POST /integrations/scripts/post-cleanup

Body parameters

Response

Related guides