The integrations API is a REST API that allows you to integrate your remote data platform with Immuta so that Immuta can manage and enforce access controls on your data.

Getting started guide

This task-based guide includes end-to-end instructions for implementing your integration - from authenticating with the API to mapping your users into Immuta so that they can access policy-enforced data. A basic request and payload example is provided for configuring each integration.

How-to guides

These guides provide step-by-step instructions for creating and managing your integration and include configuration setting examples that vary in complexity.

• Amazon S3 integration guide

• Azure Synapse Analytics integration guide

• Databricks Unity Catalog integration guide

• Google BigQuery integration guide

• Redshift integration guide

• Snowflake integration guide

• Starburst (Trino) integration guide

Reference guides

These guides define request and body parameters, response schema, and common error messages.

• Integrations API endpoints

• Integrations API payload

• Response schema

• HTTP status codes and error messages

The integrations API is a REST API that allows you to integrate your remote data platform with Immuta so that Immuta can manage and enforce access controls on your data.

To configure an integration using the API, you must have the APPLICATION_ADMIN Immuta permission.

Authenticate with the API

There are two methods for making an authenticated request to the integrations API. Select a tab below for instructions.

Configure your integration

Use the POST /integrations endpoint to configure the integration so that Immuta can enforce access controls on tables registered as Immuta data sources. See a section below for a sample request and details about configuring your integration.

Amazon S3 example

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"
    }
    }'

2. Copy the request example.

4. Change the config values to your own, where

   • name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.

   • awsAccountId is the ID of your AWS account.

   • awsRegion is the account's AWS region (such as us-east1).

   • awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.

   • awsLocationPath is the base S3 location prefix that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.

   • awsAccessKeyId is the AWS access key ID of the AWS account configuring the integration.

   • awsSecretAccessKey is the AWS secret access key of the AWS account configuring the integration.

Azure Synapse Analytics example

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": "immuta",
        "database": "sample_database",
        "username": "taylor@synapse.com",
        "password": "abc1234",
        "authenticationType": "userPassword"
    }
    }'

• host is the URL of your Azure Synapse Analytics account.

• schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

• database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

• username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

Databricks Unity Catalog example

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",
        "token": "REDACTED",
        "catalog": "immuta"
    }
    }'

• workspaceUrl is your Databricks workspace URL.

• httpPath is the HTTP path of your Databricks cluster or SQL warehouse.

• token is the Databricks personal access token. This is the access token for the Immuta system account user.

• catalog is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

Google BigQuery example

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\"}"
    }
    }'

2. Copy the request example. The example uses JSON format, but the request also accepts YAML.

4. Change the config values to your own, where

   • role is the Google Cloud role used to connect to Google BigQuery.

   • datasetSuffix is the suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore.

   • dataset is the name of the BigQuery dataset to provision inside of the project for Immuta metadata storage.

   • location is the dataset's location, which can be any valid GCP location (such as us-east1).

Redshift example

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"
    }
    }'

• host is the URL of your Redshift account.

• database is the name of a new empty database that the Immuta system user will manage and store metadata in.

• initialDatabase is the name of an existing database in Redshift that Immuta initially connects to and creates the Immuta-managed database.

• authenticationType is the type of authentication to use when connecting to Redshift.

• username and password are the credentials for the system account that can act on Redshift objects and configure the integration.

Snowflake example

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"
    }
    }'

• host is the URL of your Snowflake account.

• warehouse is the default pool of Snowflake compute resources the Immuta system user will use to run queries and perform other Snowflake operations.

• database is the name of a new empty database that the Immuta system user will manage and store metadata in.

• authenticationType is the type of authentication to use when connecting to Snowflake.

• username and password are the credentials for the system account that can act on Snowflake objects and configure the integration.

Starburst (Trino) example

1. Copy

   curl -X 'POST' \
       'https://www.organization.immuta.com/integrations' \
       -H 'accept: application/json' \
       -H 'Content-Type: application/json' \
       -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
       -d '{
       "type": "Trino"
       }'

2. Navigate to the Immuta App Settings page and click the Integrations tab.

3. Click your enabled Starburst (Trino) integration and copy the configuration snippet displayed.

Protect your data

Map usernames and create policies before you register your metadata to ensure that policies are enforced on tables and views immediately.

2. Build global policies in Immuta to enforce access controls:

Register metadata

Register your metadata using the API or Immuta UI:

• API how-to guides

Additional resources

How-to guides

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

Reference guides

See the following reference guides for information about the integrations API endpoints, payloads, and responses:

The Starburst (Trino) resource allows you to create and manage your Starburst (Trino) integration. In this integration, Immuta policies are translated into Starburst rules and permissions and applied directly to tables within users’ existing catalogs.

Use the /integrations endpoint to

Requirements

• APPLICATION_ADMIN Immuta permission

• A valid

Configure the integration

To configure the Starburst (Trino) integration, complete the following steps:

Generate the configuration snippet

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f' \
    -d '{
    "type": "Trino"
    }'

1. Copy the request example. The example provided uses JSON format, but the request also accepts YAML.

Response

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [ ]
  }
}

{
  "statusCode": 422,
  "error": "Unprocessable entity",
  "message": "Validation of prerequisite setup failed. Unable to create integration."
}

Configure the cluster

1. Navigate to the Immuta App Settings page and click the Integrations tab.

2. Click your enabled Starburst (Trino) integration and copy the configuration snippet displayed.

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

Response

{
  "id": "123456789",
  "status": "enabled",
  "type": "Trino",
  "config": {
    "apiKey": "3ea2cde7******461b02ebaa"
  }
}

Get all integrations

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

1. Copy the request example.

Response

[
  {
    "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",
        "token": "REDACTED",
        "audit": {
          "enabled": false
        },
        "catalog": "immuta"
      }
    }
  }
]

Delete an integration

curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

3. Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

{
  "id": "123456789",
  "status": "deleting",
  "validationResults": {
    "status": "passed",
    "validationTests": []
  }
}

Immuta’s integration with Unity Catalog allows you to manage multiple Databricks workspaces through Unity Catalog while protecting your data with Immuta policies. Instead of manually creating UDFs or granting access to each table in Databricks, you can author your policies in Immuta and have Immuta manage and enforce Unity Catalog access-control policies on your data in Databricks clusters or SQL warehouses.

Use the /integrations endpoint to

• configure a Databricks Unity Catalog integration

• get a Databricks Unity Catalog integration

• get all integrations

• update a Databricks Unity Catalog integration

• delete a Databricks Unity Catalog integration

Permissions

An Immuta user with the APPLICATION_ADMIN permission must configure a Databricks Unity Catalog integration.

A Databricks user authorized to create a Databricks service principal must create one for Immuta. This service principal is used continuously by Immuta to orchestrate Unity Catalog policies and maintain state between Immuta and Databricks. This service principal needs the following Databricks privileges:

• USE CATALOG and MANAGE on all catalogs containing securables registered as Immuta data sources and USE SCHEMA on all schemas containing securables registered as Immuta data sources.

• MODIFY and SELECT on all securables registered as Immuta data sources. MANAGE and MODIFY are required so that the service principal can apply row filters and column masks on the securable; to do so, the service principal must also have SELECT on the securable as well as USE CATALOG on its parent catalog and USE SCHEMA on its parent schema. Since privileges are inherited, you can grant the service principal the MODIFY and SELECT privilege on all catalogs or schemas containing Immuta data sources, which automatically grants the service principal the MODIFY and SELECT privilege on all current and future securables in the catalog or schema. The service principal also inherits MANAGE from the parent catalog for the purpose of applying row filters and column masks, but that privilege must be set directly on the parent catalog in order for grants to be fully applied.

See the Databricks documentation for more details about Unity Catalog privileges and securable objects.

Optionally, to include audit, the service principal needs the following additional privileges:

• USE CATALOG on system catalog

• USE SCHEMA on system.access schema

• SELECT on system.access.audit table

• SELECT on system.access.table_lineage table

• SELECT on system.access.column_lineage table

Access to system tables is governed by Unity Catalog. No user has access to these system schemas by default. To grant access, a user that is both a metastore admin and an account admin must grant USE and SELECT permissions on the system schemas to the service principal. See Manage privileges in Unity Catalog. The system.access schema must also be enabled on the metastore before it can be used.

Prerequisite

Enable Databricks Unity Catalog on the Immuta app settings page:

1. Click the App Settings icon in the left sidebar.

2. Scroll to the Global Integrations Settings section and check the Enable Databricks Unity Catalog support in Immuta checkbox. Leave the additional settings in this section with their default values. They are only relevant to the Databricks Spark with Unity Catalog integration and will not have any effect on the Unity Catalog integration.

Configure the integration

You have two options for configuring your Databricks Unity Catalog integration:

• Automatic setup: When performing an automatic setup, the Databricks personal access token you configure below must be attached to an account with these Databricks permissions for the metastore associated with the specified Databricks workspace. Immuta creates the catalogs, schemas, tables, and functions using the integration's configured personal access token.

• Manual setup: Run the Immuta script in Databricks yourself to create the catalog. You can also modify the script to customize your storage location for tables, schemas, or catalogs. The user running the script needs to have the CREATE CATALOG permission on the workspace metastore. The Databricks personal access token you configure must be attached to an account with the Databricks permissions listed in the requirements section.

Automatic setup

Required permissions: When performing an automatic setup, the Immuta service principal must have the permissions listed above and the CREATE CATALOG privilege on the Unity Catalog metastore.

Copy the request example, and replace the values with your own as directed to configure the integration settings. The example provided uses JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

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",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • workspaceUrl is your Databricks workspace URL.

   • httpPath is the HTTP path of your Databricks cluster or SQL warehouse.

   • token is the Databricks personal access token. This is the access token for the Immuta system account user.

   • catalog is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

Response

The response returns the status of the Databricks Unity Catalog integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Metastore validation",
      "status": "passed"
    }, {
      "name": "Basic Connection Test",
      "result": [
      {
        "1": 1
      }
      ],
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Databricks Unity Catalog integration already exists on www.example-workspace.cloud.databricks.com (id = 123456789)"
}

Manual setup

Required permissions: When performing a manual setup, the Databricks permissions listed above for the user running the script and the Immuta system account user are required.

To manually configure the integration, complete the following steps:

1. Generate the Immuta script and run it in your Databricks environment.

2. Configure the integration in Immuta.

Generate the script

Copy the request example, and replace the values with your own as directed to configure the integration settings. The example provided uses JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

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": "Databricks",
    "autoBootstrap": false,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • workspaceUrl is your Databricks workspace URL.

   • httpPath is the HTTP path of your Databricks cluster or SQL warehouse.

   • token is the Databricks personal access token. This is the access token for the Immuta system account user.

   • catalog is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

3. Run the script returned in the response in your Databricks environment.

Response

The response returns the script for you to run in your environment.

Configure the integration in Immuta

Copy the request example, and replace the values with your own as directed to configure the integration settings. The example provided uses JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when generating the script.

See the config object description for parameter definitions, value types, and additional configuration options.

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": false,
    "config": {
      "workspaceUrl": "www.example-workspace.cloud.databricks.com",
      "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
      "token": "REDACTED",
      "catalog": "immuta"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the script, where

   • workspaceUrl is your Databricks workspace URL.

   • httpPath is the HTTP path of your Databricks cluster or SQL warehouse.

   • token is the Databricks personal access token. This is the access token for the Immuta system account user.

   • catalog is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

Response

The response returns the status of the Databricks Unity Catalog integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Metastore validation",
      "status": "passed"
    }, {
      "name": "Basic Connection Test",
      "result": [
      {
        "1": 1
      }
      ],
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Databricks Unity Catalog integration already exists on www.example-workspace.cloud.databricks.com (id = 123456789)"
}

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the GET /integrations endpoint.

Response

The response returns a Databricks Unity Catalog 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": "Metastore validation",
      "status": "passed"
    }, {
      "name": "Basic Connection Test",
      "result": [
      {
        "1": 1
      }
      ],
      "status": "passed"
    }
    ]
  },
  "type": "Databricks",
  "autoBootstrap": false,
  "config": {
    "port": 443,
    "workspaceUrl": "www.example-workspace.cloud.databricks.com",
    "httpPath": "sql/protocolv1/o/0/0000-00000-abc123",
    "token": "REDACTED",
    "audit": {
      "enabled": false
    },
    "catalog": "immuta"
  }
}

Get all integrations

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

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

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",
        "token": "REDACTED",
        "audit": {
          "enabled": false
        },
        "catalog": "immuta"
      }
    }
  }
]

Update an integration configuration

Copy the request example, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -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",
      "token": "REDACTED",
      "groupPattern": {
        "deny": "admins"
      },
      "catalog": "immuta"
    }
    }'

This example updates the access token.

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • workspaceUrl is your Databricks workspace URL.

   • httpPath is the HTTP path of your Databricks cluster or SQL warehouse.

   • token is the Databricks personal access token. This is the access token for the Immuta system account user.

   • catalog is the name of the Databricks catalog Immuta will create to store internal entitlements and other user data specific to Immuta. This catalog will only be readable for the Immuta service principal and should not be granted to other users. The catalog name may only contain letters, numbers, and underscores and cannot start with a number.

Response

The response returns the status of the Databricks Unity Catalog integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Metastore validation",
      "status": "passed"
    }, {
      "name": "Basic Connection Test",
      "result": [
      {
        "1": 1
      }
      ],
      "status": "passed"
    }
    ]
  }
}

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

Delete an integration

curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

The response returns the status of the Databricks Unity Catalog 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": "Metastore validation",
      "status": "passed"
    }, {
      "name": "Basic Connection Test",
      "result": [
      {
        "1": 1
      }
      ],
      "status": "passed"
    }
    ]
  }
}

The how-to guides in this section illustrate how to integrate your remote data platform with Immuta so you can manage and enforce access controls on your data.

Amazon S3 integration API guide

Immuta's Amazon S3 integration allows users to apply subscription policies to data in S3 to restrict what prefixes, buckets, or objects users can access. To enforce access controls on this data, Immuta creates S3 grants that are administered by S3 Access Grants, an AWS feature that defines access permissions to data in S3.

Follow this guide to configure and manage your Amazon S3 integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.

Azure Synapse Analytics integration API guide

In this integration, Immuta generates policy-enforced views in a schema in your configured Azure Synapse Analytics Dedicated SQL pool for tables registered as Immuta data sources.

Follow this guide to configure and manage your Azure Synapse Analytics integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.

Databricks Unity Catalog integration API guide

Immuta’s integration with Unity Catalog allows you to manage multiple Databricks workspaces through Unity Catalog while protecting your data with Immuta policies. Instead of manually creating UDFs or granting access to each table in Databricks, you can author your policies in Immuta and have Immuta manage and enforce Unity Catalog access-control policies on your data in Databricks clusters or SQL warehouses.

Follow this guide to configure and manage your Databricks Unity Catalog integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.

Google BigQuery integration API guide

In this integration, Immuta generates policy-enforced views in your configured Google BigQuery dataset for tables registered as Immuta data sources.

Follow this guide to configure and manage your Google BigQuery integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.

Redshift integration API guide

Immuta generates policy-enforced views in your configured Redshift schema for tables registered as Immuta data sources.

Follow this guide to configure and manage your Redshift integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.

Snowflake integration API guide

Immuta manages access to Snowflake tables by administering Snowflake row access policies and column masking policies on those tables, allowing users to query tables directly in Snowflake while dynamic policies are enforced.

Follow this guide to configure and manage your Snowflake integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.

Starburst (Trino) integration API guide

Immuta policies are translated into Starburst rules and permissions and applied directly to tables within users’ existing catalogs.

Follow this guide to configure and manage your Starburst (Trino) integration. Example requests and responses are provided throughout the guide so that you can quickly copy and update them with your own settings.

The Amazon S3 resource allows you to create, configure, and manage your S3 integration. In this integration, Immuta provides coarse-grained access controls for data in S3 by performing permission grants using the Access Grants API so that users don't have to manage individual IAM policies themselves.

Use the /integrations endpoint to

• configure an S3 integration

• get an S3 integration

• get all integrations

• delete an S3 integration

Requirements

• S3 integration enabled in Immuta; contact your Immuta representative to enable this integration

• No location is registered in your AWS Access Grants instance before configuring the integration in Immuta

Permissions

• APPLICATION_ADMIN Immuta permission to configure the integration

• CREATE_S3_DATASOURCE Immuta permission to register S3 data sources

• The AWS account credentials or optional AWS IAM role you provide Immuta when configuring the integration must

  • have ownership of the buckets Immuta will enforce policies on

  • have the following permissions to create locations and issue grants:

    • s3:CreateAccessGrant

    • s3:CreateAccessGrantsLocation

    • s3:DeleteAccessGrant

    • s3:DeleteAccessGrantsLocation

    • s3:GetAccessGrant

    • s3:GetAccessGrantsInstance

    • s3:GetAccessGrantsInstanceForPrefix

    • s3:GetAccessGrantsInstanceResourcePolicy

    • s3:GetAccessGrantsLocation

    • s3:ListAccessGrants

    • s3:ListAccessGrantsInstances

    • s3:ListAccessGrantsLocations

    • iam:PassRole

    • iam:GetRole

Set up S3 Access Grants instance

1. Follow AWS documentation to create an Access Grants instance using the S3 console, AWS CLI, AWS SDKs, or the REST API. AWS supports one Access Grants instance per region per AWS account.

2. Follow the instructions at the top of the "Register a location" page in AWS documentation to create an AWS IAM role and give the S3 Access Grants service principal access to this role in the resource policy file. You will add this role to your integration configuration in Immuta so that Immuta can register this role with your Access Grants location. The AWS documentation linked above gives a complete policy example, but your policy should include the following permissions:

   • sts:AssumeRole

   • sts:SetSourceIdentity

   • sts:SetContext

3. Follow the instructions at the top of the "Register a location" page in AWS documentation to create an IAM policy with the following permissions, and attach the policy to the IAM role you created to grant the permissions to the role. The AWS documentation linked above gives a complete example, but the policy should at least include the following permissions:

   • s3:GetObject

   • s3:GetObjectVersion

   • s3:GetObjectAcl

   • s3:GetObjectVersionAcl

   • s3:ListMultipartUploadParts

   • s3:PutObject

   • s3:PutObjectAcl

   • s3:PutObjectVersionAcl

   • s3:DeleteObject

   • s3:DeleteObjectVersion

   • s3:AbortMultipartUpload

   • s3:ListBucket

   • s3:ListAllMyBuckets

   • iam:passRole

   If you use server-side encryption with AWS Key Management Service (AWS KMS) keys to encrypt your data, the following permissions are required for the IAM role in the policy. If you do not use this feature, do not include these permissions in your IAM policy:

   • kms:Decrypt

   • kms:GenerateDataKey

4. Opt to create an AWS IAM role that Immuta can use to create Access Grants locations and issue grants. This role must have the S3 permissions listed in the permissions section.

Configure the integration in Immuta

AWS S3 access key example

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"
    }
    }'

1. Copy the request example. The example uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Change the config values to your own, where

   • name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.

   • awsAccountId is the ID of your AWS account.

   • awsRegion is the account's AWS region (such as us-east1).

   • awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.

   • awsLocationPath is the base S3 location prefix that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.

   • awsAccessKeyId is the AWS access key ID of the AWS account configuring the integration.

   • awsSecretAccessKey is the AWS secret access key of the AWS account configuring the integration.

AWS S3 automatic authentication example

This request configures the integration using the automatic authentication method, which searches and obtains credentials using the AWS SDK's default credential provider chain. This method requires a configured IAM role for a service account and is only supported if you're using a self-managed deployment of Immuta. Work with your Immuta representative to customize your deployment and set up an IAM role for a service account that can give Immuta the credentials to set up the integration.

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": "auto"
    }
    }'

1. Copy the request example. The example uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Change the config values to your own, where

   • name is the name for the integration that is unique across all Amazon S3 integrations configured in Immuta.

   • awsAccountId is the ID of your AWS account.

   • awsRegion is the account's AWS region (such as us-east1).

   • awsLocationRole is the AWS IAM role ARN assigned to the base access grants location. This is the role the AWS Access Grants service assumes to vend credentials to the grantee.

   • awsLocationPath is the base S3 location that Immuta will use for this connection when registering S3 data sources. This path must be unique across all S3 integrations configured in Immuta.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the S3 integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "There is no existing integration matching this configuration",
      "status": "passed"
    },
    {
      "name": "The provided integration name is unique across Immuta S3 integrations",
      "status": "passed"
    },
    {
      "name": "The provided access grants location role is a valid ARN format",
      "status": "passed"
    },
    {
      "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
      "status": "passed"
    },
    {
      "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
      "status": "passed"
    },
    {
      "name": "The provided S3 path exists and Immuta can list prefixes",
      "status": "passed"
    },
    {
      "name": "An AWS Access Grants location does not yet exist for the provided path",
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Access Grants location already exists on provided path."
}

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the GET /integrations endpoint.

Response

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

{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
      {
        "name": "There is no existing integration matching this configuration",
        "status": "passed"
      },
      {
        "name": "The provided integration name is unique across Immuta S3 integrations",
        "status": "passed"
      },
      {
        "name": "The provided access grants location role is a valid ARN format",
        "status": "passed"
      },
      {
        "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
        "status": "passed"
      },
      {
        "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
        "status": "passed"
      },
      {
        "name": "The provided S3 path exists and Immuta can list prefixes",
        "status": "passed"
      },
      {
        "name": "An AWS Access Grants location does not yet exist for the provided path",
        "status": "passed"
      }
    ]
  },
  "type": "Native S3",
  "autoBootstrap": false,
  "config": {
    "port": 443,
    "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"
  }
  }

Get all integrations

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

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

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": "123456789",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "There is no existing integration matching this configuration",
          "status": "passed"
        },
        {
          "name": "The provided integration name is unique across Immuta S3 integrations",
          "status": "passed"
        },
        {
          "name": "The provided access grants location role is a valid ARN format",
          "status": "passed"
        },
        {
          "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
          "status": "passed"
        },
        {
          "name": "The provided S3 path exists and Immuta can list prefixes",
          "status": "passed"
        },
        {
          "name": "An AWS Access Grants location does not yet exist for the provided path",
          "status": "passed"
        }
      ] },
      "type": "Native S3",
      "autoBootstrap": false,
      "config": {
        "port": 443,
        "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"
      }
  }
]

Delete an integration

curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

The response returns the status of the S3 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": "The provided access grants location role is a valid ARN format",
        "status": "passed"
      },
      {
        "name": "The provided AWS credentials allow fetching the caller's identity via the AWS STS API",
        "status": "passed"
      },
      {
        "name": "An AWS Access Grants instance is configured in the provided AWS account and region",
        "status": "passed"
      },
      {
        "name": "The provided S3 path exists and Immuta can list prefixes",
        "status": "passed"
      }
    ]
  }
}

The Google BigQuery resource allows you to create, configure, and manage your Google BigQuery integration. In this integration, Immuta generates policy-enforced views in your configured Google BigQuery dataset for tables registered as Immuta data sources.

Use the /integrations endpoint to

• configure a Google BigQuery integration

• get a Google BigQuery integration

• get all integrations

• update a Google BigQuery integration

• delete a Google BigQuery integration

Requirements

• APPLICATION_ADMIN Immuta permission

• Google BigQuery integration enabled in Immuta (work with your Immuta representative to enable this integration)

• To execute the Immuta script from your command line to create a Google Cloud service account and role, you must be authenticated to the gcloud CLI utility as a user with all of the following roles:

  • roles/iam.roleAdmin

  • roles/iam.serviceAccountAdmin

  • roles/serviceusage.serviceUsageAdmin

Prerequisite

Create a Google Cloud service account and role by either using the Google Cloud console or the provided Immuta script.

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": "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\"}"
    }
    }'

1. Copy the request example. The example uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Change the config values to your own, where

   • role is the Google Cloud role used to connect to Google BigQuery.

   • datasetSuffix is the suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore.

   • dataset is the name of the BigQuery dataset to provision inside of the project for Immuta metadata storage.

   • location is the dataset's location, which can be any valid GCP location (such as us-east1).

   • credential is the Google BigQuery service account JSON keyfile credential content. See the Google documentation for guidance on generating and downloading this keyfile.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the Google BigQuery integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Basic Validation: Verify service account not being used for data source connection credentials",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Immuta Service Account postfix",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Non-matching service account in key file",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Connection can be made to BigQuery",
      "status": "passed"
    },
    {
      "name": "Initialize Validation: [Dataset - exists] innate-conquest-123456.immuta",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Dataset - create] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Table - create] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Table - insert] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "warning",
      "message": "Billing has not been enabled for this project. Enable billing at https://console.cloud.google.com/billing. DML queries are not allowed in the free tier. Set up a billing account to remove this restriction.. Confirm that the bootstrap script was executed without any modifications. This warning will not prevent the connection but continue at your own risk as some features may not function."
    },
    {
      "name": "Validate Manual: [Table - get] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE (After insert)",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - update] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - get] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE (After update)",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - delete] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Dataset - delete] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144",
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Google BigQuery integration already exists on host organization.cloud.google.com (id = 123456789)"
}

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the GET /integrations endpoint.

Response

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

{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Basic Validation: Verify service account not being used for data source connection credentials",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Immuta Service Account postfix",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Non-matching service account in key file",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Connection can be made to BigQuery",
      "status": "passed"
    },
    {
      "name": "Initialize Validation: [Dataset - exists] innate-conquest-123456.immuta",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Dataset - create] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Table - create] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Table - insert] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "warning",
      "message": "Billing has not been enabled for this project. Enable billing at https://console.cloud.google.com/billing. DML queries are not allowed in the free tier. Set up a billing account to remove this restriction.. Confirm that the bootstrap script was executed without any modifications. This warning will not prevent the connection but continue at your own risk as some features may not function."
    },
    {
      "name": "Validate Manual: [Table - get] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE (After insert)",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - update] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - get] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE (After update)",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - delete] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Dataset - delete] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144",
      "status": "passed"
    }
    ]
  },
  "type": "Google BigQuery",
  "autoBootstrap": false,
  "config": {
    "port": 443,
    "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"
    }
  }
  }

Get all integrations

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

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

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",
        "token": "REDACTED",
        "audit": {
          "enabled": false
        },
        "catalog": "immuta"
      }
    }
  }
]

Update an integration configuration

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\"}"
    }
    }'

1. Copy the request example, which updates the private key. The example uses JSON format, but the request also accepts YAML.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to update.

4. Change the config values to your own, where

   • role is the Google Cloud role used to connect to Google BigQuery.

   • datasetSuffix is the suffix to postfix to the name of each dataset created to store secure views. This string must start with an underscore.

   • dataset is the name of the BigQuery dataset to provision inside of the project for Immuta metadata storage.

   • location is the dataset's location, which can be any valid GCP location (such as us-east1).

   • credential is the Google BigQuery service account JSON keyfile credential content. See the Google documentation for guidance on generating and downloading this keyfile.

See the config object description for parameter definitions, value types, and additional configuration options.

Response

The response returns the status of the Google BigQuery integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Basic Validation: Verify service account not being used for data source connection credentials",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Immuta Service Account postfix",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Non-matching service account in key file",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Connection can be made to BigQuery",
      "status": "passed"
    },
    {
      "name": "Initialize Validation: [Dataset - exists] innate-conquest-123456.immuta",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Dataset - create] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Table - create] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Table - insert] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "warning",
      "message": "Billing has not been enabled for this project. Enable billing at https://console.cloud.google.com/billing. DML queries are not allowed in the free tier. Set up a billing account to remove this restriction.. Confirm that the bootstrap script was executed without any modifications. This warning will not prevent the connection but continue at your own risk as some features may not function."
    },
    {
      "name": "Validate Manual: [Table - get] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE (After insert)",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - update] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - get] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE (After update)",
      "status": "skipped"
    },
    {
      "name": "Validate Manual: [Table - delete] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144.IMMUTA_VERIFY_TABLE",
      "status": "passed"
    },
    {
      "name": "Validate Manual: [Dataset - delete] innate-conquest-123456.IMMUTA_VERIFY_DATASET_144",
      "status": "passed"
    }
    ]
  }
}

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

Delete an integration

curl -X 'DELETE' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to delete.

Response

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

{
  "id": "123456789",
  "status": "deleting",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Basic Validation: Verify service account not being used for data source connection credentials",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Immuta Service Account postfix",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Non-matching service account in key file",
      "status": "passed"
    },
    {
      "name": "Basic Validation: Connection can be made to BigQuery",
      "status": "passed"
    }
    ]
  }
}

The Azure Synapse Analytics resource allows you to create, configure, and manage your Azure Synapse Analytics integration. In this integration, Immuta generates policy-enforced views in a schema in your configured Azure Synapse Analytics Dedicated SQL pool for tables registered as Immuta data sources.

Use the /integrations endpoint to

• configure an Azure Synapse Analytics integration

• get an Azure Synapse Analytics integration

• get all integrations

• update an Azure Synapse Analytics integration

• delete an Azure Synapse Analytics integration

Requirements

• APPLICATION_ADMIN Immuta permission

• A running Dedicated SQL pool

• Account used to configure or edit the integration must have the Azure Synapse Analytics permission to manage GRANTS

Configure the integration

You have two options for configuring your Azure Synapse Analytics integration:

• Automatic setup: Grant Immuta one-time use of credentials to automatically configure your Azure Synapse Analytics environment and the integration. When performing an automated installation, Immuta requires temporary, one-time use of credentials with the permission to manage GRANTS.

• Manual setup: Run the Immuta script in your Azure Synapse Analytics environment yourself to configure your environment and the integration. The specified role used to run the bootstrap needs to have the permission to manage GRANTS.

Automatic setup

Copy the request example from one of the sections below, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

Basic example

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",
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

Complex example

This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.

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",
      "impersonation": {
        "enabled": true,
        "role": "IMMUTA_IMPERSONATION"
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

Response

The response returns the status of the Azure Synapse Analytics integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Connect",
      "result": [
      {
        "SCHEMA_NAME": "sample_schema",
        "CATALOG_NAME": "immuta",
        "SCHEMA_OWNER": "taylor@synapse.com",
        "DEFAULT_CHARACTER_SET_NAME": "iso_1",
        "DEFAULT_CHARACTER_SET_SCHEMA": null,
        "DEFAULT_CHARACTER_SET_CATALOG": null
      }
      ],
      "status": "passed"
    },
    {
      "name": "Initial Validation: Delimiters",
      "status": "passed"
    },
    {
      "name": "Validate Immuta system user can manage database",
      "result": [
      {
        "name": "taylor@synapse.com"
      }
      ],
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Azure Synapse Analytics integration already exists on host organization.azure.com (id = 123456789)"
}

Manual setup

To manually configure the integration, complete the following steps:

1. Generate the first Immuta script and run it in your Azure Synapse Analytics environment.

2. Generate the second Immuta script and run it in your Azure Synapse Analytics environment.

3. Configure the integration in Immuta.

Generate the first script

Copy the request example from one of the sections below, and replace the values with your own as directed to generate the script. The examples provided use JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

Basic example

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",
      "impersonation": {
        "enabled": false
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

3. Run the script returned in the response in your Azure Synapse Analytics environment.

Complex example

This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.

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",
      "impersonation": {
        "enabled": true,
        "role": "IMMUTA_IMPERSONATION"
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Change the config values to your own, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

3. Run the script returned in the response in your Azure Synapse Analytics environment.

Response

The response returns the script for you to run in your environment.

Generate the second script

Copy the request example from one of the sections below, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when generating the first script.

See the config object description for parameter definitions, value types, and additional configuration options.

Basic example

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": "Azure Synapse Analytics",
    "autoBootstrap": false,
    "config": {
      "host": "organization.azure.com",
      "schema": "sample_schema",
      "database": "immuta",
      "impersonation": {
        "enabled": false
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the first script, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

3. Run the script returned in the response in your Azure Synapse Analytics environment.

Complex example

This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.

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": "Azure Synapse Analytics",
    "autoBootstrap": false,
    "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"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the first script, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

3. Run the script returned in the response in your Azure Synapse Analytics environment.

Response

The response returns the script for you to run in your environment.

Configure the integration in Immuta

Copy the request example from one of the sections below, and replace the values with your own as directed to configure the integration settings. The examples provided use JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when generating the scripts.

See the config object description for parameter definitions, value types, and additional configuration options.

Basic example

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": false,
    "config": {
      "host": "organization.azure.com",
      "schema": "sample_schema",
      "database": "immuta",
      "impersonation": {
        "enabled": false
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the scripts, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

Complex example

This request enables impersonation to allow Immuta administrators to grant users permission to query Azure Synapse Analytics data as other Immuta users.

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": false,
    "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"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Pass the same payload you sent when generating the scripts, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

Response

The response returns the status of the Azure Synapse Analytics integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "creating",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Connect",
      "result": [
      {
        "SCHEMA_NAME": "sample_schema",
        "CATALOG_NAME": "immuta",
        "SCHEMA_OWNER": "taylor@synapse.com",
        "DEFAULT_CHARACTER_SET_NAME": "iso_1",
        "DEFAULT_CHARACTER_SET_SCHEMA": null,
        "DEFAULT_CHARACTER_SET_CATALOG": null
      }
      ],
      "status": "passed"
    },
    {
      "name": "Initial Validation: Delimiters",
      "status": "passed"
    },
    {
      "name": "Validate Immuta system user can manage database",
      "result": [
      {
        "name": "taylor@synapse.com"
      }
      ],
      "status": "passed"
    }
    ]
  }
}

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Azure Synapse Analytics integration already exists on host organization.azure.com (id = 123456789)"
}

Get an integration

curl -X 'GET' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: 846e9e43c86a4ct1be14290d95127d13f'

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

3. Replace the {id} request parameter with the unique identifier of the integration you want to get. Alternatively, you can get a list of all integrations and their IDs with the GET /integrations endpoint.

Response

The response returns an Azure Synapse Analytics 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: Connect",
      "result": [
      {
        "SCHEMA_NAME": "sample_schema",
        "CATALOG_NAME": "immuta",
        "SCHEMA_OWNER": "taylor@synapse.com",
        "DEFAULT_CHARACTER_SET_NAME": "iso_1",
        "DEFAULT_CHARACTER_SET_SCHEMA": null,
        "DEFAULT_CHARACTER_SET_CATALOG": null
      }
      ],
      "status": "passed"
    },
    {
      "name": "Initial Validation: Delimiters",
      "status": "passed"
    },
    {
      "name": "Validate Immuta system user can manage database",
      "result": [
      {
        "name": "taylor@synapse.com"
      }
      ],
      "status": "passed"
    }
    ]
  },
  "type": "Azure Synapse Analytics",
  "autoBootstrap": true,
  "config": {
    "host": "organization.azure.com",
    "schema": "sample_schema",
    "database": "immuta",
    "port": 1433,
    "impersonation": {
      "enabled": false
    },
    "metadataDelimiters": {
      "hashDelimiter": "|",
      "hashKeyDelimiter": "-",
      "arrayDelimiter": ","
    },
    "username": "<REDACTED>"
  }
}

{
  "id": "123456789",
  "status": "enabled",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Connect",
      "result": [
      {
        "SCHEMA_NAME": "sample_schema",
        "CATALOG_NAME": "immuta",
        "SCHEMA_OWNER": "taylor@synapse.com",
        "DEFAULT_CHARACTER_SET_NAME": "iso_1",
        "DEFAULT_CHARACTER_SET_SCHEMA": null,
        "DEFAULT_CHARACTER_SET_CATALOG": null
      }
      ],
      "status": "passed"
    },
    {
      "name": "Initial Validation: Delimiters",
      "status": "passed"
    },
    {
      "name": "Validate Immuta system user can manage database",
      "result": [
      {
        "name": "taylor@synapse.com"
      }
      ],
      "status": "passed"
    }
    ]
  },
  "type": "Azure Synapse Analytics",
  "autoBootstrap": true,
  "config": {
    "host": "organization.azure.com",
    "schema": "sample_schema",
    "database": "immuta",
    "port": 1433,
    "impersonation": {
      "enabled": true,
      "role": "IMMUTA_IMPERSONATION"
    },
    "metadataDelimiters": {
      "hashDelimiter": "|",
      "hashKeyDelimiter": "-",
      "arrayDelimiter": ","
    },
    "username": "<REDACTED>"
  }
}

Get all integrations

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

1. Copy the request example.

2. Replace the Immuta URL and API key with your own.

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",
        "token": "REDACTED",
        "audit": {
          "enabled": false
        },
        "catalog": "immuta"
      }
    }
  }
]

Update an integration configuration

You have two options for updating your integration. Follow the steps that match your initial configuration of autoBootstrap:

• automatic update (autoBootstrap is true)

• manual update (autoBootstrap is false)

Automatic update

Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -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"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

Response

The response returns the status of the Azure Synapse Analytics integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Connect",
      "result": [
      {
        "SCHEMA_NAME": "sample_schema",
        "CATALOG_NAME": "immuta",
        "SCHEMA_OWNER": "taylor@synapse.com",
        "DEFAULT_CHARACTER_SET_NAME": "iso_1",
        "DEFAULT_CHARACTER_SET_SCHEMA": null,
        "DEFAULT_CHARACTER_SET_CATALOG": null
      }
      ],
      "status": "passed"
    },
    {
      "name": "Initial Validation: Delimiters",
      "status": "passed"
    },
    {
      "name": "Validate Immuta system user can manage database",
      "result": [
      {
        "name": "taylor@synapse.com"
      }
      ],
      "status": "passed"
    }
    ]
  }
}

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

Manual update

To manually update the integration, complete the following steps:

1. Generate the updated Immuta script and run it in your Azure Synapse Analytics environment.

2. Update the integration in Immuta.

Generate the updated script

Copy the request example, and replace the values with your own as directed to generate the script. The example provided uses JSON format, but the request also accepts YAML.

See the config object description for parameter definitions, value types, and additional configuration options.

curl -X 'POST' \
    'https://www.organization.immuta.com/integrations/{id}/scripts/edit' \
    -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",
      "impersonation": {
        "enabled": false
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Change the config values to your own, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

4. Run the script returned in the response in your Azure Synapse Analytics environment.

Response

The response returns the script for you to run in your environment.

Update the integration in Immuta

Copy the request example, and replace the values with your own as directed to update the integration settings. The example provided uses JSON format, but the request also accepts YAML. The payload you provide must match the payload sent when generating the updated script.

See the config object description for parameter definitions, value types, and additional configuration options.

curl -X 'PUT' \
    'https://www.organization.immuta.com/integrations/{id}' \
    -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",
      "impersonation": {
        "enabled": false
      },
      "metadataDelimiters": {
        "hashDelimiter": "|",
        "hashKeyDelimiter": "-",
        "arrayDelimiter": ","
      },
      "username": "taylor@synapse.com",
      "password": "abc1234",
      "authenticationType": "userPassword"
    }
    }'

1. Replace the Immuta URL and API key with your own.

2. Replace the {id} request parameter with the unique identifier of the integration you want to update.

3. Pass the same payload you sent when generating the script, where

   • host is the URL of your Azure Synapse Analytics account.

   • schema is the name of the Immuta-managed schema where all your secure views will be created and stored.

   • database is the name of an existing database where the Immuta system user will store all Immuta-generated schemas and views.

   • impersonation specifies whether user impersonation is enabled. See the object description for child parameters.

   • metadataDelimeters are a set of delimiters that Immuta uses to store profile data in Azure Synapse Analytics. See the object description for child parameters.

   • username and password are the username and password of the system account that can act on Azure Synapse Analytics objects and configure the integration.

Response

The response returns the status of the Azure Synapse Analytics integration configuration connection. See the response schema reference for details about the response schema.

{
  "id": "123456789",
  "status": "editing",
  "validationResults": {
    "status": "passed",
    "validationTests": [
    {
      "name": "Initial Validation: Connect",
      "result": [
      {
        "SCHEMA_NAME": "sample_schema",
        "CATALOG_NAME": "immuta",
        "SCHEMA_OWNER": "taylor@synapse.com",
        "DEFAULT_CHARACTER_SET_NAME": "iso_1",
        "DEFAULT_CHARACTER_SET_SCHEMA": null,
        "DEFAULT_CHARACTER_SET_CATALOG": null
      }
      ],
      "status": "passed"
    },
    {
      "name": "Initial Validation: Delimiters",
      "status": "passed"
    },
    {
      "name": "Validate Immuta system user can manage database",
      "result": [
      {
        "name": "taylor@synapse.com"
      }
      ],
      "status": "passed"
    }
    ]
  }
}