> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/SaaS/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/SaaS/developer-guides/api-intro/connections-api/how-to-guides/manage-connection-settings.md).

# Manage Connection Settings

This page details the `/data` v1 API options available for connection-level objects.

* For a how-to on registering a connection, see the [Register a connection guide](/SaaS/developer-guides/api-intro/connections-api/how-to-guides/register-a-connection.md).
* For details on the `/data` v1 API options available for objects within a connection, see the [Manage connection objects guide](/SaaS/developer-guides/api-intro/connections-api/how-to-guides/manage-a-connection.md).

These endpoints are only available to connections from the following technologies:

* Snowflake
* Databricks Unity Catalog
* AWS Lake Formation

| Method  | Endpoint                                                                                                  | Description                                                    |
| ------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| **GET** | [<mark style="color:blue;">`/data/connection/{connectionKey}`</mark>](#get-data-connection-connectionkey) | Search for a connection using a connection key                 |
| **PUT** | [<mark style="color:blue;">`/data/connection/{connectionKey}`</mark>](#put-data-connection-connectionkey) | Update the connection information for the specified connection |

## <mark style="color:green;">`GET`</mark> `/data/connection/{connectionKey}`

Search for a connection using a connection key.

**Required Immuta permission**: `CREATE_DATA_SOURCE`, `APPLICATION_ADMIN`, `GOVERNANCE`, or data owner within the hierarchy

```
curl -X 'GET' \
  'https://your-immuta-url.com/data/connection/yourConnectionKey' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-bearer-token'
```

#### Path parameters

<table><thead><tr><th width="197">Attribute</th><th width="414">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>connectionKey</strong> <code>string</code></td><td>The key to uniquely identify the connection. This is the same as the display name of the connection in the Immuta UI.</td><td><strong>Yes</strong></td></tr></tbody></table>

#### Response schema

<table><thead><tr><th width="197">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>connectionKey</strong> <code>string</code></td><td>The key to uniquely identify the connection.</td></tr><tr><td><strong>connection</strong> <code>object</code></td><td>Integration-specific connection information (i.e., hostname, authentication type, warehouse, etc.)</td></tr><tr><td><strong>createdAt</strong> <code>timestamp</code></td><td>The time the connection was registered in Immuta.</td></tr><tr><td><strong>createdBy</strong> <code>integer</code></td><td>The ID of the user who registered the connection.</td></tr><tr><td>creator.<strong>id</strong> <code>integer</code></td><td>The ID of the user who registered the connection.</td></tr><tr><td>creator.<strong>name</strong> <code>string</code></td><td>The name of the user who registered the connection.</td></tr><tr><td>creator.<strong>email</strong> <code>string</code></td><td>The email of the user who registered the connection.</td></tr><tr><td><strong>updatedAt</strong> <code>timestamp</code></td><td>The time the connection was updated in Immuta.</td></tr><tr><td><strong>updatedBy</strong> <code>integer</code></td><td>The ID of the user who updated the connection.</td></tr><tr><td>updater.<strong>id</strong> <code>integer</code></td><td>The ID of the user who updated the connection.</td></tr><tr><td>updater.<strong>name</strong> <code>string</code></td><td>The name of the user who updated the connection.</td></tr><tr><td>updater.<strong>email</strong> <code>string</code></td><td>The email of the user who updated the connection.</td></tr><tr><td><strong>nativeIntegrationId</strong> <code>integer</code></td><td>The ID of the integration backing the connection.</td></tr></tbody></table>

#### Example response

```
{
  "connectionKey": "yourConnectionKey",
  "connection": {
    "port": 443,
    "role": "IMMUTA_SNOWFLAKE_ROLE",
    "hostname": "example.us-east-1.snowflakecomputing.com",
    "username": "IMMUTA_DB_SYSTEM_ACCOUNT",
    "warehouse": "your-warehouse",
    "technology": "Snowflake",
    "authenticationType": "userPassword"
  },
  "createdAt": "2023-12-22T18:28:46.328Z",
  "createdBy": 2,
  "updatedAt": "2023-12-22T18:28:46.328Z",
  "updatedBy": 2,
  "creator": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "taylor@immuta.com"
  },
  "updater": {
    "id": 2,
    "name": "Taylor Smith",
    "email": "taylor@immuta.com"
  },
  "nativeIntegrationId": 1
}
```

## <mark style="color:green;">`PUT`</mark> `/data/connection/{connectionKey}`

Update the connection information for the specified connection. Partial updates are not supported. Using this endpoint, you can only update connection information. To update other integration details, use the [<mark style="color:blue;">PUT</mark> <mark style="color:blue;">`/integrations/{id}`</mark>](/SaaS/developer-guides/api-intro/integrations-api/reference-guides/integrations-api.md#put-integrations-id) endpoint.

**Required Immuta permission**: `APPLICATION_ADMIN`

{% hint style="warning" %}
**Updating credentials triggers a full crawl of the connection**

If connection credentials are changed, Immuta triggers a full crawl to validate that it still has access to all data objects, disable anything it no longer has access to, and pull any new objects coming from the new credentials.
{% endhint %}

{% tabs %}
{% tab title="Snowflake username and password" %}

```
curl -X 'PUT' \
    'https://<your-immuta-url>/data/connection/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     "connection": {
       "technology": "Snowflake",
       "hostname": "<your-Snowflake-hostname-url>",
       "port": <your-Snowflake-port>,
       "warehouse": "<your-Snowflake-warehouse>",
       "role": "<your-Snowflake-role>",
       "authenticationType": "userPassword",
       "username": "<your-Snowflake-username>",
       "password": "<your-Snowflake-password>"
     }
    }'
```

{% endtab %}

{% tab title="Snowflake key pair" %}

```
curl -X 'PUT' \
    'https://<your-immuta-url>/data/connection/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     "connection": {
       "technology": "Snowflake",
       "hostname": "<your-Snowflake-hostname-url>",
       "port": <your-Snowflake-port>,
       "warehouse": "<your-Snowflake-warehouse>",
       "role": "<your-Snowflake-role>",
       "authenticationType": "keyPair",
       "username": "<the-Snowflake-username>",
       "privateKeyPassword": "<your-Snowflake-key-password>",
       "privateKey": {
         "keyName": "PRIV_KEY_FILE",
         "userFilename": "<your-private-key-file-name>",
         "content": "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->"
       }
     }
    }'
```

{% endtab %}

{% tab title="Snowflake OAuth with certificate" %}

```
curl -X 'PUT' \
    'https://<your-immuta-url>/data/connection/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     "connection": {
       "technology": "Snowflake",
       "hostname": "<your-Snowflake-hostname-url>",
       "port": <your-Snowflake-port>,
       "warehouse": "<your-Snowflake-warehouse>",
       "role": "<your-Snowflake-role>",
       "authenticationType": "oAuthClientCredentials",
       "oAuthClientConfig": {
         "useCertificate": true,
         "clientId": "<your-client-ID>",
         "authorityUrl": "<your-example.authority.com>",
         "scope": "session:role-any",
         "publicCertificateThumbprint": "<your-certificate-thumbprint>",
         "resource": "<your-optional-resource>",
         "oauthPrivateKey": {
           "keyName": "oauth client certificate",
           "userFilename": "<your-user-file.pem>",
           "content": "<-----BEGIN PRIVATE KEY-----your-private-key-----END PRIVATE KEY----->"
         }
       }
     }
    }'
```

{% endtab %}

{% tab title="Snowflake OAuth with secret" %}

```
curl -X 'PUT' \
    'https://<your-immuta-url>/data/connection/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     "connection": {
       "technology": "Snowflake",
       "hostname": "<your-Snowflake-hostname-url>",
       "port": <your-Snowflake-port>,
       "warehouse": "<your-Snowflake-warehouse>",
       "role": "<your-Snowflake-role>",
       "authenticationType": "oAuthClientCredentials",
       "oAuthClientConfig": {
         "useCertificate": false,
         "clientId": "<your-client-ID>",
         "authorityUrl": "<your-example.authority.com>",
         "scope": "session:role-any",
         "resource": "<your-optional-resource>",
         "clientSecret": "<your-client-secret>"
       }
     }
    }'
```

{% endtab %}

{% tab title="Databricks Unity Catalog" %}

```
curl -X 'PUT' \
    'https://<your-immuta-url>/data/connection/yourConnectionKey' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: <your-bearer-token>' \
    -d '{
     "connection": {
       "technology": "Databricks",
       "hostname": "<www.your-workspace.cloud.databricks.com>",
       "port": <your-Databricks-port>,
       "httpPath": "<your-Databricks-warehouse-path>",
       "authenticationType": "token",
       "token": "<your-service-principal-pat>"
     }
    }'
```

{% endtab %}
{% endtabs %}

#### Path parameters

| Attribute                  | Description                                                                                                           | Required |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- |
| **connectionKey** `string` | The key to uniquely identify the connection. This is the same as the display name of the connection in the Immuta UI. | **Yes**  |

#### Body parameters

The connection parameters differ based on your backing technology. See the [Connection registration payload reference guide](/SaaS/developer-guides/api-intro/connections-api/connection-registration-payloads-reference-guide.md) for details about the payloads.

#### Response schema

<table><thead><tr><th width="147">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>objectPath</strong> <code>string</code></td><td>The list of names that uniquely identify the path to a data object in the remote platform's hierarchy. The first element should be the <code>connectionKey</code> and all names are separated by forward slashes.</td></tr><tr><td><strong>bulkId</strong> <code>string</code></td><td>A bulk ID that can be used to search for the status of background jobs triggered by this request.</td></tr></tbody></table>

#### Example response

```
{
  "objectPath": ['yourConnectionKey'],
  "bulkId": "a-new-uuid"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.immuta.com/SaaS/developer-guides/api-intro/connections-api/how-to-guides/manage-connection-settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.