Agentic Data Access Reference Guide

Private preview: This feature is available to select accounts. Contact your Immuta representative for details.

Immuta’s agentic data access allows an AI agent to have policies that define its data access or to temporarily act for a human user so that the agent can query data while respecting the human user’s data access. To enable acting on behalf of a user, Immuta vends an ephemeral role that allows the agent to inherit the user’s specific permissions temporarily.

What happens when a user uses Immuta’s agentic data access?

1. The human requester starts a session with an agent and the service that manages that agent uses the Immuta agent’s API key to request that Immuta vend an ephemeral role.

2. Immuta vends the ephemeral role in the data platform, inheriting the unioned permissions of both the human and the agent based on defined policies.

3. The data platform lets Immuta know the ephemeral role is ready, and Immuta lets the agent's service that called the API know.

4. The agent service then connects to the data platform using the agent's personal credentials with that new ephemeral role.

5. The human requester can now ask the agent a question about their data.

6. The agent uses the ephemeral role to query the data platform with the appropriate access.

7. The data platform returns the data and the agent provides that to the human requester.

8. Optionally, the agent service can prompt for the ephemeral role to be dropped; however, this will happen based on the expiration automatically.

Identities

Immuta’s agentic data access introduces a new identity type: agents. There are now two separate identities in Immuta:

• Users: These are the human users in your organization, which should be registered via an IAM. Users can log into Immuta, have permissions in Immuta, and complete actions in the Immuta UI. They can also be granted attributes and groups and have policies applied to them.

• Agents: These are the AI agents of your organization, which can be created manually or through an IAM. Agents cannot log into Immuta and can only interact with Immuta by using the API to request the ephemeral role. However, they can be granted attributes and groups and have policies applied to them.

What does Immuta create in my environment?

As with human users, agents are granted access to data through roles (or groups) in the data platform. So when using agents and agentic access, Immuta will create two new roles, in addition to the human user roles that have always been used for policy application:

• Human user roles: Each human user created in Immuta will be granted a role with the access they are given. This user role will be created whether or not the user has an account in the data platform. Note that Immuta already behaves this way and this is not specific to this feature.

• Agent roles: Each agent created in Immuta will be granted a role with the access it is given (if any).

• Ephemeral roles: Each session where a human user chats with an agent to understand or engineer data, that agent service will request that Immuta vends an ephemeral role for that session that will allow the agent to access data that either it or the user can query.

Setting up the agent service

Each agent from an agent service must be registered in Immuta as an agent. This allows for the agent to have policies that define its data access, if desired, but more importantly so it can request the ephemeral roles. See the Manage agents page for details on how to create an agent identity in Immuta.

Once the user admin creates the agent in Immuta, they can use the UI or API to create an API key for that specific agent. An example of this request is,

curl -X 'POST' \
    'https://www.organization.immuta.com/bim/iam/{iamid}/user/{userid}/apikeys' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <USER_ADMIN_TOKEN>' \
    -d '{
    "name": "Marketing department agent API key",
    "expiration": "2027-03-23"
    }'

This request creates a new API key for the agent and sets an expiration for the key. This API key can then be added to the agent service to use when requesting the ephemeral role.

Requesting the ephemeral role

The agent service calls Immuta's API using the agent’s API key to request for the ephemeral role to be created. An example of this request is,

curl -X POST "https://your-immuta-url.com/bim/agent/obo/roles" \
     -H "Authorization: Bearer <AGENT_ACCESS_TOKEN>" \
     -H 'Content-Type: application/json' \
     -d '{
       "userid": "<the authenticated human>",
       "technology": ["snowflake", "databricks"],
       "ttl": "30m"
     }'

This request provides all the information that Immuta needs to vend the ephemeral role:

• The AGENT_ACCESS_TOKEN is the agent’s API key and allows Immuta to know the agent being used.

• The userid is the authenticated human user’s Immuta ID and allows Immuta to know the human user involved in the request. The agent service should validate and authenticate this user within the service. This user does not need to exist in the data platform.

• The technology is the data platform the agent will be querying.

• The TTL (Time To Live) is the amount of time the role will be active before it automatically expires.

Policy unions

In order to streamline agent services, Immuta allows for optionally defining access for agents which allows them to complete agentic tasks without having to also grant that same data to every human. When a human user asks an agent a question and Immuta vends an ephemeral role for the request, the ephemeral role combines the human user’s and the agent’s privileges in the data platform.

Typically the type of access will be different depending on the identity:

• Agent access: The agents will generally be granted access to public data needed to do its job, such as lookup tables or semantic layers.

• Human access: Humans should be granted access to sensitive data specific to their roles and responsibilities in the business.

Consider the following scenario:

• Active data policy: Only show rows where the department column matches a user’s group.

• Active subscription policies:

  • Grant access to tables tagged revenue to identities with attribute Type:Analyst.

  • Grant access to tables tagged dimension to members of group Agents.

Human user identity

• Name: Taylor

• Group: finance

• Attribute: Type:Analyst

• Account: Immuta

Agent identity

• Name: General use agent

• Group: Agents

• Accounts: Immuta, Snowflake, Databricks

Immuta vends a temporary role to the agent, and Taylor's entitlements are combined with the agent's:

• Groups: finance and Agents

• Attributes: Type:Analyst

Taylor then prompts the agent:

Show me last month's revenue broken down by region and department.

Agent thinking...

The agent queries the data platform for data to answer the requester's question. It queries the 2026_revenue table tagged revenue which joins on a dimension table tagged dimension to find the region. The join might look something like the following sample:

invoice_id	date	region	department	amount
INV-2026021	2026-02-03	North America	finance	12,345.67
INV-2026027	2026-02-08	EMEA	finance	9,876.54
INV-2026029	2026-02-15	APAC	finance	45,678.90
...	....	...	....	...

Taylor did not have direct access to the region lookup (dimension) table, but because of the policy union, they could see it through the agent’s access. However, the data policy was still respected, and only the rows that matched the data policy were returned.

Once the agent completes its data collection, the agent responds with the following data:

region	total_revenue
North America	$1,234,567
EMEA	$987,654
APAC	$456,789

Understanding policy calculation at scale

The access provided to the vended role is pre-calculated and does not require Immuta to run any table grants in the data platform at question time. Instead, it leverages role hierarchies and group parent/child relationships depending on the data platform, making it scale.

The result is an agent that can reference the tables and columns it needs in near real time, when a request is made, but the data returned is constrained to what the human has permission to see through Immuta policies.

Audit

Immuta’s agentic access provides transparent auditing of which identity is querying data. The agent has an activity tab that shows which role was vended for which users so it can be cross referenced in your data platform query history, or vice versa. This allows you to understand if a query was an agent was acting on behalf of a user or not.