> 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/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md).

# Connecting the Agent to the Data Platform

Connect the agent you registered in Immuta to your data platform so the agent can run queries on behalf of users

{% hint style="info" %}
**Public preview**: This feature is available to all accounts that request to enable it for their tenant. Contact your Immuta representative to enable it.
{% endhint %}

In order for agents registered in Immuta to run queries or act on behalf of users, you must connect the agent to your data platform. The sections below outline dependencies, scripts, and example requests for connecting agents to [Databricks](#databricks) and [Snowflake](#snowflake).

## Databricks

### Dependencies

* Ensure your Immuta customer success representative has enabled the Immuta Agentic Data Access feature.
* You must be using the [group grants version](https://documentation.immuta.com/saas/configuration/integrations/databricks/databricks-unity-catalog/how-to-guides/granting-to-groups-for-databricks-unity-catalog.md) of the Immuta Databricks integration. If you're unsure of whether or not you're using that version, contact your customer success representative.
* Enable the **Databricks** [Role-based access control (RBAC)](https://docs.databricks.com/aws/en/release-notes/product/2026/august#role-based-access-control-rbac-is-generally-available) feature. To enable RBAC, an account admin must turn on the feature at the account level. Workspace admins then enable it in each workspace.

If you are planning to use the Agentic Data Access feature on a Databricks [connection](https://documentation.immuta.com/saas/configuration/integrations/registering-a-connection/reference-guides/connections-overview.md) that already existed in Immuta prior to the feature being enabled, you must run this script using the same user account that created the Immuta Databricks connection in question. This must be done manually since the original setup script was run by you, the customer, when setting up the connection and Immuta does not have permission to create tables.

```sql
--
-- System table used for data-only impersonation for OBO (on-behalf-of) agents
--
-- Primary keys are informational, not enforceable, in Databricks.
-- Uniqueness is enforced by the application layer via MERGE on vended_group.
-- vended_group is the logical primary key: one agent maps to one impersonated user at a time.
CREATE TABLE IF NOT EXISTS `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` (
    vended_group STRING NOT NULL PRIMARY KEY,
    impersonated_user STRING NOT NULL,
    created_at TIMESTAMP NOT NULL
);

-- Enable default values so the created_at column can have a default
ALTER TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` SET TBLPROPERTIES('delta.feature.allowColumnDefaults' = 'supported');
-- Set the default value for created_at to the current time
ALTER TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` ALTER COLUMN created_at SET DEFAULT CURRENT_TIMESTAMP();

--
-- Revoke direct access from account users - only the Immuta service account should
-- read and write this table
--
REVOKE SELECT,MODIFY ON TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` FROM `account users`;

--
-- Transfer ownership to the Immuta service account
--
ALTER TABLE `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` OWNER TO `<immuta system account>`;


CREATE OR REPLACE VIEW `<immuta system catalog>`.`immuta_system`.`__immuta_user` AS
  SELECT p.*
  FROM `<immuta system catalog>`.`immuta_system`.`__immuta_profiles` p
  LEFT JOIN `<immuta system catalog>`.`immuta_system`.`__immuta_obo_agent_impersonation` obo
    ON upper(obo.vended_group) = upper(current_user())
  WHERE upper(p.`immuta__userid`) =
    CASE
      -- OBO Agent Impersonation
      WHEN obo.impersonated_user IS NOT NULL THEN upper(obo.impersonated_user)
      -- Default Identity
      ELSE upper(current_user())
    END;
```

### Creating and mapping the agent account in Databricks

* It is best practice for the agent account in Databricks to be a service principal. Follow Databricks' documentation for creating [service principals](https://docs.databricks.com/aws/en/admin/users-groups/manage-service-principals#-add-service-principals-to-your-account).
* Once your service principal is created, [map it to the agent in Immuta](https://documentation.immuta.com/saas/agentic-data-access/manage-agents.md#map-the-agent-to-external-data-platforms). The external username must be the **service principal UUID** (the application ID) and not the name. You can retrieve the [service principal's UUID from Databricks](https://docs.databricks.com/api/account/accountserviceprincipals/get).

### Connecting to Databricks as the agent

You must connect to Databricks exclusively via OAuth M2M (machine-to-machine) authentication using a scoped token.

Rather than connecting as a static service account, the agent harness (not the agent itself) first calls Immuta's on-behalf-of (OBO) API to obtain an ephemeral vended group scoped to the end user's entitlements, and then exchanges the service principal credentials for a short-lived OAuth token that assumes that group's identity. This ensures every query executed against Databricks is scoped to exactly what the end user is permitted to access, with full auditability via the vended group name in query history.

See the [Databricks documentation](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m.html) for guidance, but here is an example request:

```shellscript
curl -s -X POST \
  -u "$DATABRICKS_SP_CLIENT_ID:$DATABRICKS_SP_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=sql&assume_group=<nativeRoleId>" \
  "https://<your-databricks-workspace-host>/oidc/v1/token"
```

In this example, `assume_group=<nativeRoleId>` is the group ID that was returned from the [Immuta agentic access V1 API](https://documentation.immuta.com/saas/agentic-data-access/manage-agents.md#request-an-ephemeral-role-and-connect-the-agent-to-the-data-platform). This ensures the access is scoped to *that group only*. [The response](https://documentation.immuta.com/saas/agentic-data-access/agentic-data-access-reference-guide.md#requesting-the-ephemeral-role) from the Immuta agentic access V1 API will include the name and the ID of the vended group. *You must use the ID* in the OAuth M2M authentication's `assume_group`.

You may require more scopes for your agent than `sql`, but if you only intend to have it fetch data over SQL, that is the least-privileged scope necessary.

{% hint style="warning" %}
Databricks Unity Catalog groups are an eventually consistent system, meaning changes are not reflected *immediately*. Because of this, you may see a delay waiting for the vended group because Immuta must wait for group inheritance to fully sync from Unity Catalog. Databricks is actively working to improve this latency.
{% endhint %}

### Ensuring the agent account can run queries

Immuta does not manage access to compute, so in order for the agent to execute queries, remembering that the agent connects as itself, you must manually assign a warehouse.

See the [Databricks documentation](https://docs.databricks.com/aws/en/sql/language-manual/security-grant) for guidance, but here is an example statement that grants the agent `USAGE` on a warehouse:

```sql
-- Grant usage to the SQL Warehouse
GRANT USAGE ON WAREHOUSE `<warehouse_name>` TO SERVICE PRINCIPAL `<agent_account>`;      
```

## Snowflake

### Dependencies

Ensure your Immuta customer success representative has enabled the Immuta Agentic Data Access feature.

### Creating and mapping the agent account in Snowflake

* The agent account in Snowflake must be a SERVICE\_AGENT type user. See the [Snowflake documentation](https://docs.snowflake.com/en/user-guide/admin-user-management#types-of-users) for guidance, but here is an example statement that sets the agent as a SERVICE\_AGENT type user:

```sql
ALTER USER "<agent name>" SET TYPE = SERVICE_AGENT;
```

* Once your SERVICE\_AGENT account is created, [map it to the agent in Immuta](https://documentation.immuta.com/saas/agentic-data-access/manage-agents.md#map-the-agent-to-external-data-platforms).

### Connecting to Snowflake as the agent

{% hint style="success" %}
**Recommended**: Snowflake's [OAuth token exchange for agent delegation](https://docs.snowflake.com/en/user-guide/oauth-token-exchange) is purpose-built for exactly this pattern and is the preferred way to connect the agent to Snowflake.
{% endhint %}

You can watch a quick demonstration of how Immuta interacts with Snowflake agent delegation here:

{% embed url="<https://youtu.be/l-iUXQRjVm0>" %}

#### **OAuth token exchange for agent delegation**

Snowflake's agent delegation model maps directly onto how Immuta's agentic access already works: the agent authenticates as *itself*, using a credential that proves its own standing identity, and that identity is then scoped down — per request — to exactly the role Immuta vended for the current user. Nothing about the agent's own privileges changes; the session it opens is bounded to just the vended role for its lifetime.

Concretely, the agent harness completes the following steps:

1. It requests the ephemeral role from Immuta as usual (see [Requesting the ephemeral role](https://documentation.immuta.com/saas/agentic-data-access/agentic-data-access-reference-guide.md#requesting-the-ephemeral-role)).
2. It exchanges a standing credential for the agent's own Snowflake user for a short-lived (≈1 hour) access token scoped to that vended role by calling Snowflake's token exchange endpoint:

```bash
curl -X POST "https://<account_identifier>.snowflakecomputing.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token=${AGENT_SUBJECT_TOKEN}" \
  --data-urlencode "subject_token_type=programmatic_access_token" \
  --data-urlencode 'scope=session:role:"IMMUTA_VENDED_<id>"' \
  --data-urlencode 'act={"sub":"<agent_name>","type":"agent"}'
```

{% hint style="warning" %}
**Quote the role in `scope`**

The vended role name is always mixed case with special characters (e.g., `IMMUTA_VENDED_57ef1e5f-...`). Snowflake uppercases unquoted identifiers, so passing the role bare gets it normalized to all-caps and the exchange fails with "role not granted to this user," even though it clearly is. Wrap the vended role name in double quotes inside the `scope` value, as shown in the snippet above.

If your account has `QUOTED_IDENTIFIERS_IGNORE_CASE` set to `true`, note that — unlike the SQL API's `role` field — the token exchange endpoint has no equivalent per-request parameter to override it, so quoting-based behavior under that setting is unverified; confirm with Snowflake support before relying on it in that configuration.
{% endhint %}

3. It uses the returned token to execute the query, with `X-Snowflake-Authorization-Token-Type: OAUTH`.

```bash
curl -s -X POST "https://<account>.snowflakecomputing.com/api/v2/statements" \
  -H "Authorization: Bearer ${DELEGATED_TOKEN}" \
  -H "X-Snowflake-Authorization-Token-Type: OAUTH" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "statement": "<sql statement>",
        "timeout": 60,
        "resultSetMetaData": {"format": "json"}
      }'
```

{% hint style="info" %}
Snowflake documentation describes the response body as the token JSON-encoded as a string (e.g., `"eyJraWQi..."`). In practice, it has returned as the bare JWT with no surrounding quotes, despite a `content-type: application/json` header. Harness implementations should accept either shape rather than assuming the body is valid JSON.
{% endhint %}

#### **Choosing a subject token**

The `subject_token` proves the agent's own identity going into the exchange. Immuta's vended role is what actually restricts the resulting session, not this credential, so it doesn't need (and shouldn't have) a role restriction of its own. Snowflake supports three subject token types. The table below lists them in order of preference.

| Subject token type                                                                          | When to use it                                                                                                                                  | Tradeoff                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Workload identity federation** (`urn:snowflake:token-type:wif`)                           | The agent harness runs in a cloud compute environment with a native identity (AWS/Azure/GCP instance role, GKE workload identity, etc.).        | This is the best option. There is no stored secret at all; the cloud provider mints a short-lived token on demand. Requires [configuring WIF](https://docs.snowflake.com/en/user-guide/workload-identity-federation) for the agent's Snowflake user.                                                                                                         |
| **Snowflake/External OAuth access token** (`urn:ietf:params:oauth:token-type:access_token`) | Your organization already has an IdP (Okta, Entra ID, PingFederate, etc.) and wants the agent's identity centrally managed and revocable there. | This is a short-lived, non-static secret in the agent's environment, but it requires standing up an [External OAuth security integration](https://docs.snowflake.com/en/user-guide/oauth-ext-overview) mapped to the agent's Snowflake user.                                                                                                                 |
| **Programmatic access token** (`programmatic_access_token`)                                 | You want a fast set-up with no IdP or cloud-identity integration required.                                                                      | This is the simplest option, but this is a long-lived static secret you're responsible for protecting and rotating. Create **one**, with no role restriction, and reuse it for every exchange. Never mint a new one per query (Snowflake caps a user at 15 active PATs, and minting one per query will exhaust that limit in any reasonably active session). |

For the PAT path, create the standing credential once:

```sql
ALTER USER <agent_name> ADD PROGRAMMATIC ACCESS TOKEN <token_name>
  DAYS_TO_EXPIRY = 90
  COMMENT = 'Standing credential for Immuta agent delegation — not used directly for queries';
```

{% hint style="info" %}
**Built-in audit attribution**

Every session opened from a delegated token is automatically attributed to the agent via the `act` parameter. It shows up as `agent_type = EXTERNAL_AGENT` in `QUERY_HISTORY` and in the `agents_info` field of `ACCESS_HISTORY`, giving you agent-level audit visibility for free. See [Audit agent activity](https://docs.snowflake.com/en/user-guide/oauth-token-exchange#audit-agent-activity) for details.
{% endhint %}

### Ensuring the agent account can run queries

Immuta does not manage access to compute, so in order for the agent to execute queries, you must manually assign a warehouse.

See the [Snowflake documentation](https://docs.snowflake.com/en/sql-reference/sql/grant-privilege) for guidance, but here is an example statement that grants the agent `USAGE` on a warehouse to the agent's standing role:

```sql
ALTER SESSION SET QUOTED_IDENTIFIERS_IGNORE_CASE = FALSE; -- Only required if your Snowflake account is set to QUOTED_IDENTIFIERS_IGNORE_CASE = TRUE

-- Grant usage to warehouse
GRANT USAGE ON WAREHOUSE <WAREHOUSE> TO ROLE "<agent_role_created_by_immuta>"; 
```

{% hint style="warning" %}
`<agent_role_created_by_immuta>` is **not** the vended role. Rather, it's the role that is permanently assigned to the agent in Snowflake. The creation of this role occurs once you [map the Immuta agent to the Snowflake account](#creating-and-mapping-the-agent-account-in-snowflake) and it is named `<immuta_integration_prefix>_AGENT_<agent_name>`.
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.immuta.com/saas/agentic-data-access/manage-agents/connecting-the-agent-to-the-data-platform.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
