Manage Agent Identities

Understand the parameters and response schema of the agent endpoints

The agent API allows users to create and manage vended roles from agent identities in Immuta. To create the agent identities, use the IAM API.

Endpoints and methods

Method	Endpoint	Description
GET	/agent/{agentId}/activity	Get the activity for an agent
POST	/agent/obo/roles	Create a vended role for an agent
DELETE	/agent/obo/roles/{id}	Delete all vended roles for an agent
GET	/agent/obo/roles/{id}	View the status of an agent

GET /agent/{agentId}/activity

Get the specific events where the agent vended a role on behalf of the user.

Required Immuta permission: USER_ADMIN

curl -X GET "https://your.immuta.url.com/agent/100/activity" \
     -H "Authorization: Bearer 09a0ffd7512f4aeeb66c09f3111c436c" \
     -H 'Content-Type: application/json'

Path parameter

Parameter	Description
agentId string	The user ID of the agent.

Query parameter

Parameter	Description	Required or optional	Accepted values
startDate timestamp	The beginning of the window to view activity.	Optional	Must be an ISO 8601 timestamp. Defaults to 7 days in the past.
endDate timestamp	The end of the window to view activity.	Optional	Must be an ISO 8601 timestamp. Defaults to the current time.
offset integer	The number of items from the beginning of the response to exclude. You can combine the offset and size parameters to return a specific set of events. For example, to return the second and third event in the response, you would set offset=1 and size=2.	Optional	Minimum value is 0. Maximum value is the total number of events minus size.
size integer	The number of events to return.	Optional	Minimum value is 1. Maximum value is the total number of events.
search string	The text to search for in the usernames of human users. This will return agent activity on-behalf-of users with a name that contains this search text.	Optional	-

Response attributes

Attribute	Description
data array	A list of the individual events within the searched window where the specific agent vended a role on behalf of a user.
data.userId integer	The user the agent was acting on behalf of for the activity event.
data.userIamId string	The IAM of the user the agent was acting on behalf of for the activity event.
data.userName string	The username of the user the agent was acting on behalf of for the activity event.
data.vendedRoleName string	The name of the specific vended role.
data.createdAt timestamp	When the vended role was created.
data.expiresAt timestamp	When the vended role expires.
total integer	The total number of events in the searched window where a vended role was created by the agent on behalf of the user.
chartData array	An array of timestamps for each specific instance where the agent vended a role.

Response

{
  "data": [
    {
      "userId": 1,
      "userIamId": "bim",
      "userName": "Taylor",
      "vendedRoleName": "IMMUTA_VENDED_42_1_abc-123",
      "createdAt": "2026-01-01T00:00:00Z",
      "expiresAt": "2026-01-01T01:00:00Z"
    }
  ],
  "total": 1,
  "chartData": ["2026-01-01T00:00:00Z"]
}

POST /agent/obo/roles

Create vended roles for an agent acting on behalf of a user.

Requirement: Must be an agent type identity making the call with their API key

curl -X POST "https://your.immuta.url.com/agent/obo/roles" \
     -H "Authorization: Bearer 09a0ffd7512f4aeeb66c09f3111c436c" \
     -H 'Content-Type: application/json' \
     -d '{
     "userid": "[email protected]",
     "technology": ["snowflake", "databricks"],
     "ttl": "30m"
     }'

Body parameters

Parameter	Description	Required or optional	Default values	Accepted values
userid string	The authenticated human user’s Immuta ID. This 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.	Required	-	-
technology array	A list of the data platform technologies to vend roles for.	Required	-	Snowflake Databricks
ttl string	The time the vended role will be active before it expires.	Optional	1h	Accepted pattern: ^(\d+)(m|h)$

Response

Returns a vended role object.

{
  "id": "735",
  "roles": {
    "Snowflake": {
      "roleName": "Marketing dashboard",
      "status": "READY"
    },
    "Databricks": {
      "roleName": "Finance data",
      "status": "READY"
    }
  },
  "expiresAt": "2026-04-02T11:45:00.000Z"
}

DELETE /agent/obo/roles/{id}

Marks all vended platform roles as expired for a specific vended role ID.

Requirement: Must be an agent type identity making the call with their API key

curl -X DELETE "https://your.immuta.url.com/agent/obo/roles/0002002" \
     -H "Authorization: Bearer 09a0ffd7512f4aeeb66c09f3111c436c"

Path parameter

Parameter	Description
id string	The ID of the agent's vended role. Can be found in the response when creating the vended role.

Response

The response will return 200 if successful.

Example error response

• 404 if the vended role ID doesn’t exist

GET /agent/obo/roles/{id}

View the specific vended role and its status by ID.

Requirement: Must be an agent type identity making the call with their API key

curl -X GET "https://your.immuta.url.com/agent/obo/roles/0002002" \
     -H "Authorization: Bearer 09a0ffd7512f4aeeb66c09f3111c436c"

Path parameter

Parameter	Description
id string	The ID of the agent's vended role. Can be found in the response when creating the vended role.

Response

Returns the requested vended role object.

Vended role object attributes

Attribute	Description
id string	The unique identifier of the vended role.
roles object	Objects for each vended role created for each platform.
roles.{technology} object	An object for the vended role created for the specific platform.
roles.{technology}.roleName string	The name of the vended role created for that specific platform.
roles.{technology}.status string	The status of the vended role created for that specific platform. Options include CREATING, READY, FAILED, EXPIRED, and DROPPED.
expiresAt timestamp	The time that the vended roles for the agent will automatically expire.