Manage Agents

Manage your agents and view agent activity

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

Register and manage agents

Create an agent

Required Immuta permission: USER_ADMIN

Register an agent in Immuta from your identity provider, by creating a new agent in Immuta, or by converting an existing user to an agent. Expand the blocks below for instructions on these methods.

Add an agent from your identity provider

1. See the how-to guide for your identity management protocol to register an existing agent in Immuta. If your identity provider uses the SAML or OpenID Connect protocol and SCIM is enabled, you can map a custom SCIM attribute to Immuta to automatically identify and register user accounts as agents. Otherwise, you must convert the user account to an agent after it is registered in Immuta.
2. Click Identities and select Users.
3. Click the overflow menu in the Actions column of the agent you just registered and click Configure dependencies.
4. Connect the agent to your data platform so the agent can run queries and act on behalf of users.

Create a new agent using the Immuta UI

1. Click Identities and select Agents.
2. Click New agent.
3. Enter a Name for your agent, select an Owner, and provide an optional description.
4. Click Create agent.
5. Connect the agent to your data platform so the agent can run queries and act on behalf of users.

Convert an existing user to an agent

User will lose all Immuta permissions If converting a user to an agent, all Immuta permissions will be removed. Agents can only act through APIs and cannot log in to Immuta.

1. Click Identities and select Users.
2. Click the overflow menu in the Actions column of the user you want to convert to an agent and select Convert to agent.
3. Click Convert to agent again to confirm your changes.
4. Connect the agent to your data platform so the agent can run queries and act on behalf of users.

Generate credentials for your agent

The credentials agents use for authentication depend on the version of the agentic access API you're using to request and manage ephemeral roles for the agent:

• Agentic access V1 API: Agents use a personal access token to authenticate.
• Deprecated legacy agentic access API: Agents use an API key to authenticate.

Click one of the tabs below for instructions on generating a personal access token or API key for your agent.

Personal access token

Requirement: USER_ADMIN Immuta permission or own the agent

The agent will use this token to make requests to the Immuta API to vend and delete ephemeral roles.

With the UI

1. Click Identities and select Agents.
2. Click the name of the agent you want to generate the API for.
3. Navigate to the Personal Access Tokens tab and click Generate Token.
4. Enter a token Description and opt to set an expiration date.
5. Click Generate token.
6. Copy the token and store it somewhere secure. It will not be visible in Immuta after closing the dialog.

This token can now be added to your agent service so that it can use it when requesting the ephemeral role.

With the API

Copy the request example below and replace the values with your own as directed to generate the agent's personal access token.

curl -X 'POST' \
    'https://www.organization.immuta.com/bim/iam/{iamId}/agent/{agentId}/tokens' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <USER_ADMIN_TOKEN>' \
    -d '{
    "description": "Marketing department agent token",
    "expirationDate": "2027-03-23"
    }'

1. Replace the Immuta URL and bearer token with your own.
2. Replace the {iamId} request parameter with the unique identifier of your identity provider. You can find this ID in the identity provider's configuration section on the app settings page or through the Immuta API. If you created the agent in Immuta, this value is bim.
3. Replace the {agentId} request parameter with the unique identifier of the agent. You can get this ID through the Immuta API and using the agent's name as a search filter, or you can get it from the Agents page in the Immuta UI.
4. Change the payload values to your own, where

   • description is a brief description of the agent's personal access token.
   • expirationDate is the date the token expires.

This token can now be added to your agent service so that it can use it when requesting the ephemeral role. For information about additional endpoints used to manage agents' personal access tokens, see the Manage IAMs API reference guide.

API key (legacy method)

Deprecation notice: Support for this method has been deprecated.

Requirement: USER_ADMIN Immuta permission or own the agent

The agent will use this API key to make requests to the Immuta API to vend and delete ephemeral roles.

With the UI

1. Click Identities and select Agents.
2. Click the name of the agent you want to generate the API for.
3. Navigate to the API Keys tab and click Generate API Key.
4. Enter an API key name and click Generate key.

This API key can now be added to your agent service so that it can use it when requesting the ephemeral role.

With the API

Copy the request example below and replace the values with your own as directed to generate the agent's API key.

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

1. Replace the Immuta URL and bearer token with your own.
2. Replace the {iamId} request parameter with the unique identifier of your identity provider. You can find this ID in the identity provider's configuration section on the app settings page or through the Immuta API. If you created the agent in Immuta, this value is bim.
3. Replace the {userId} request parameter with the unique identifier of the agent. You can get this ID through the Immuta API and using the agent's name as a search filter, or you can get it from the Agents page in the Immuta UI.
4. Change the payload values to your own, where

   • name is the name of the agent's API key.
   • expiration is the date the API key expires.

This API key can now be added to your agent service so that it can use it when requesting the ephemeral role.

Assign groups or attributes to your agent

Requirement: USER_ADMIN Immuta permission or own the agent

Opt to assign groups and attributes to the agent, just like you would for a human user. Once these entitlements are added, they can be used in global policies to target agents and grant or limit their access to data.

1. Click Identities and select Agents.
2. Click the name of the agent you want to add groups or attributes to.
3. Navigate to the Attributes or Groups tab to add these entitlements to the agent:

   • Attributes: Click Add Attributes.

     1. Begin typing the attribute name in the Attribute text box. If the attribute already exists, select it from the dropdown list. If the attribute does not exist yet, enter the full name of the attribute, and then select it from the dropdown.
     2. In the Attribute Value text box, enter a value. If the value already exists, select it from the dropdown list. If the value does not exist, enter the full name, and then select it from the dropdown.
     3. Click Close.
   • Groups: Click Add Groups.

     1. Begin typing in the Search by Group Name text box. If you need to create a new group, follow the instructions on the Manage attributes and groups page, and then add the agent to the group.
     2. Click the name in the dropdown list to add the agent to the group.
     3. Click close.

Map the agent to external data platforms

Requirement: USER_ADMIN Immuta permission or own the agent

Map external usernames to the agent account in Immuta to ensure Immuta properly enforces policies when connecting to the data platform.

The instructions below illustrate how to do this for individual agents, but you can also configure external mapping in your Identity provider connection on the app settings page.

1. Click Identities and select Agents.
2. Click the name of the agent you want to map to external data platforms.
3. Navigate to the External Mapping tab.
4. Click Edit for the data platform username you want to map to and complete the fields in the modal that appears. For guidance on what to enter in these fields, see the External user ID mapping page.

Request an ephemeral role and connect the agent to the data platform

The agent harness will use the new agentic access V1 API or the legacy agentic access API to request an ephemeral role for your agent. You will then use that ephemeral role to connect to the agent to the data platform. Expand the blocks below for guidance.

New agentic access V1 API

1. The agent harness requests an ephemeral role.

   curl \
     --request POST 'https://{globalSegment}.api.immutacloud.com/agents/roles' \
     --header 'Authorization: Bearer <AGENT_PAT>' \
     --header 'Content-Type: application/json' \
     --data '{
       "username": "[e-mail]",
       "platforms": [
         {"technology": "Snowflake"},
         {"technology": "Databricks", "connectionKeys": ["finance_dbx_conn"]}
       ],
       "ttl": "30m"
     }'

   • globalSegment should match the region your Immuta tenant is in:

     • Asia Pacific: ap
     • European Union: eu
     • North America: na
   • AGENT_PAT is the agent's personal access token.
   • username is the Immuta user ID of the human user the agent will act on behalf of. This value can be found on the user's profile page in the Immuta UI. For example, [e-mail].
   • technology is the data platform the agent will be querying.
   • ttl (time to live) is the amount of time the role will be active before it automatically expires.

   The agent harness can also specify a connection key along with the platform to target specific connections. For information about this request and the payload, see the Agentic access V1 API guide.
2. The call to vend roles is asynchronous, so roles are not guaranteed to exist after it returns a response. Therefore, the agent harness should poll the endpoint below until the status is READY. The requestId is returned in the response of the previous call and is the unique identifier assigned to that request.

   curl \
     --request GET 'https://{globalSegment}.api.immutacloud.com/agents/roles/{requestId}' \
     --header 'Authorization: Bearer <AGENT_PAT>' \
     --header 'Content-Type: application/json' \

3. Use the vended role(s) returned under the metadata field to connect to your agentic platform. The response below returns vended roles for two different connections: IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301 and 1234567890123456.

   {
     "requestId": "019fcd26-e9f8-746f-a174-fdebc0e643cf",
     "createdAt": "2026-04-02T11:15:00.000Z",
     "expiresAt": "2026-04-02T11:45:00.000Z",
     "roles": [
       {
         "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
         "name": "IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301",
         "technology": "Snowflake",
         "connectionKey": "finance_snowflake_conn",
         "status": "READY",
         "metadata": { "roleName": "IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301" }
       },
       {
         "id": "9b2504e0-4f89-11d3-9a0c-0305e82c3302",
         "technology": "Databricks",
         "name": "IMMUTA_VENDED_9b2504e0-4f89-11d3-9a0c-0305e82c3302",
         "connectionKey": "finance_dbx_conn",
         "status": "READY",
         "metadata": { "groupName": "IMMUTA_VENDED_9b2504e0-4f89-11d3-9a0c-0305e82c3302", "groupId": "1234567890123456" }
       }
     ]
   }

Legacy agentic access API

Deprecation notice: Support for this API has been deprecated.

1. The agent harness requests an ephemeral role.

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

   • your-immuta-url is the URL of your Immuta tenant.
   • AGENT_ACCESS_TOKEN is the agent's bearer token.
   • userid is the Immuta user ID of the human user the agent will act on behalf of. The userid is displayed as Username in the Immuta UI. For example, [e-mail].
   • technology is the data platform the agent will be querying.
   • ttl (time to live) is the amount of time the role will be active before it automatically expires.

   For information about this request and the payload, see the Agentic access - legacy API reference guide.
2. Use the vended role(s) returned in the roleName field to connect to your agentic platform. The response below returns vended roles for a Snowflake connection: IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301.

   {
     "id": "019fcd26-e9f8-746f-a174-fdebc0e643cf",
     "roles": {
       "Snowflake": {
         "roleName": "IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301",
         "status": "READY"
       }
     },
     "expiresAt": "2026-04-02T11:45:00.000Z"
   }

View agent activity

1. Click Identities and select Agents.
2. Click the name of the agent you want to view.
3. Click the Activity tab.

This view displays a list of vended roles, the vended role expiration dates, and the users the agent was acting on behalf of.

Disable or delete agents

Deleting agents

Only agents created in the Immuta UI can be deleted from the agents page.

Requirement: USER_ADMIN Immuta permission or own the agent

1. Click Identities and select Agents.
2. Click the overflow menu in the Action column of the agent you want to disable or delete and select Disable or Delete.
3. Click Disable or Delete again to confirm your changes.