# Configure a Starburst (Trino) Integration

{% hint style="warning" %}
**Deprecation notice**

Support for configuring the Starburst (Trino) integration using this legacy workflow has been deprecated. Instead, configure your integration and register your data using [connections](https://documentation.immuta.com/saas/configuration/integrations/starburst-trino/how-to-guides/register-a-trino-connection).
{% endhint %}

{% @mermaid/diagram content="graph LR
A(Authenticate) --> B(Configure integration) --> C(Map users and create policies) --> D(Register metadata);
style A fill:#fff
style B fill:#2F6BA7,color:#fff
style C fill:#fff
style D fill:#fff" %}

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

* [configure a Starburst (Trino) integration](#configure-the-integration)
* [get a Starburst (Trino) integration](#get-an-integration)
* [get all integrations](#get-all-integrations)
* [generate a new Immuta API key](#generate-a-new-immuta-api-key)
* [delete a Starburst (Trino) integration](#delete-an-integration)

## Requirements

* `APPLICATION_ADMIN` Immuta permission
* A valid [Starburst Enterprise license](https://docs.starburst.io/latest/license-requirements.html)

## Configure the integration

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

1. [Generate the configuration snippet](#generate-the-configuration-snippet)
2. [Configure your Starburst cluster](#configure-the-cluster)

### Generate the configuration snippet

```bash
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.
2. Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/saas/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.

#### Response

The response returns the status of the Starburst (Trino) integration configuration connection. See the [response schema reference](https://documentation.immuta.com/saas/developer-guides/api-intro/integrations-api/reference-guides/response-schema) for details about the response schema.

{% tabs %}
{% tab title="200 response" %}
A successful response includes the validation tests statuses.

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

{% endtab %}

{% tab title="Unsuccessful request" %}
An unsuccessful request returns the status code and an error message. See the [HTTP status codes and error messages](https://documentation.immuta.com/saas/developer-guides/api-intro/reference-guides/status-codes#post-errors) for a list of statuses, error messages, and troubleshooting guidance.

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

{% endtab %}
{% endtabs %}

### Configure the cluster

1. Navigate to the Immuta <i class="fa-gear">:gear:</i> **App Settings** page and click the **Integrations** tab.
2. Click your enabled **Starburst (Trino)** integration and copy the configuration snippet displayed.
3. Follow the steps in the configure the Immuta system access control plugin in [Starburst](https://documentation.immuta.com/saas/configuration/integrations/starburst-trino/how-to-guides/configure#id-2-configure-the-immuta-system-access-control-plugin-in-starburst) or [Trino](https://documentation.immuta.com/saas/configuration/integrations/starburst-trino/how-to-guides/configure#id-2-configure-the-immuta-system-access-control-plugin-in-trino) section to add the configuration in the appropriate `immuta-access-control.properties` file to finish configuring your cluster.

## Get an integration

```bash
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**](https://documentation.immuta.com/saas/developer-guides/api-intro/getting-started#authenticate-with-the-api) 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 [<mark style="color:blue;">`GET /integrations`</mark> <mark style="color:blue;">endpoint</mark>](https://documentation.immuta.com/saas/developer-guides/api-intro/reference-guides/integrations-api#get-integrations).

### Response

The response returns a Starburst (Trino) integration configuration and the Immuta API key used to configure the Starburst cluster. See the [response schema reference](https://documentation.immuta.com/saas/developer-guides/api-intro/integrations-api/reference-guides/response-schema) 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](https://documentation.immuta.com/saas/developer-guides/api-intro/reference-guides/status-codes#get-error) for a list of statuses, error messages, and troubleshooting guidance.

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

## Get all integrations

```bash
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**](https://documentation.immuta.com/saas/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.

### Response

The response returns the configuration for all integrations. See the [response schema reference](https://documentation.immuta.com/saas/developer-guides/api-intro/integrations-api/reference-guides/response-schema) 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](https://documentation.immuta.com/saas/developer-guides/api-intro/reference-guides/status-codes#get-error) for a list of statuses, error messages, and troubleshooting guidance.

```json
[
  {
    "id": "1",
    "status": "enabled",
    "validationResults": {
      "status": "passed",
      "validationTests": [
        {
          "name": "Initial Validation: Basic Connection Test",
          "status": "passed"
        },
        {
          "name": "Initial Validation: Default Warehouse Access Test",
          "status": "passed",
          "result": []
        },
        {
          "name": "Initial Validation: Validate access to Privileged Role",
          "status": "passed",
          "result": []
        },
        {
          "name": "Validate Automatic: Database Does Not Exist",
          "status": "passed"
        },
        {
          "name": "Validate Automatic: Impersonation Role Does Not Exist",
          "status": "skipped"
        },
        {
          "name": "Validate Automatic Bootstrap User Grants",
          "status": "passed"
        }
      ]
    },
    "type": "Snowflake",
    "autoBootstrap": true,
    "config": {
      "host": "organization.us-east-1.snowflakecomputing.com",
      "warehouse": "SAMPLE_WAREHOUSE",
      "database": "SNOWFLAKE_SAMPLE_DATA",
      "port": 443,
      "audit": {
        "enabled": false
      },
      "workspaces": {
        "enabled": false
      },
      "impersonation": {
        "enabled": false
      },
      "lineage": {
        "enabled": false
      },
      "authenticationType": "userPassword",
      "username": "<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"
    }
  }
]
```

## Generate a new Immuta API key

{% hint style="warning" %}
**Cluster restart required**

To update your API key in Starburst (Trino), you must shut down your cluster, generate and update the API key, and then restart your cluster. If you do not shut down your cluster, generating a new API key using the endpoint below will cause downtime for your deployment.
{% endhint %}

1. [Disable your Starburst (Trino) cluster](https://docs.starburst.io/starburst-galaxy/cluster-administration/create-edit-and-delete-galaxy-clusters.html#cluster-disable).
2. Copy the request example below and replace these values:

   * Replace the **Immuta URL** and [**API key**](https://documentation.immuta.com/saas/developer-guides/api-intro/getting-started#authenticate-with-the-api) with your own.
   * Replace the **{id}** request parameter with the unique identifier of the Starburst (Trino) integration you want to regenerate the Immuta API key for.

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

   Once you make this request, your old Immuta API key will be deleted and will no longer be valid.
3. The response includes your new Immuta API key. [Replace the old <mark style="color:blue;">`immuta.apikey`</mark> value in the Immuta access control properties file](https://documentation.immuta.com/saas/configuration/integrations/starburst-trino/how-to-guides/configure#id-2-configure-the-immuta-system-access-control-plugin-in-starburst) with this new key.
4. [Enable your Starburst (Trino) cluster](https://docs.starburst.io/starburst-galaxy/cluster-administration/create-edit-and-delete-galaxy-clusters.html#enable-a-cluster).

### Response

The response includes your new Immuta API key.

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

## Delete an integration

```bash
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**](https://documentation.immuta.com/saas/developer-guides/api-intro/getting-started#authenticate-with-the-api) 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 Starburst (Trino) integration configuration that has been deleted. See the [response schema reference](https://documentation.immuta.com/saas/developer-guides/api-intro/integrations-api/reference-guides/response-schema) 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](https://documentation.immuta.com/saas/developer-guides/api-intro/reference-guides/status-codes#delete-errors) for a list of statuses, error messages, and troubleshooting guidance.

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