# Manage Agent Identities

The agent API allows users to create and manage [vended roles from agent identities](/saas/agentic-data-access/introduction.md) in Immuta. To create the agent identities, [use the IAM API](/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/bim.md).

## Endpoints and methods

| Method     | Endpoint                                                                                        | Description                          |
| ---------- | ----------------------------------------------------------------------------------------------- | ------------------------------------ |
| **GET**    | [<mark style="color:$primary;">`/agent/{agentId}/activity`</mark>](#get-agent-agentid-activity) | Get the activity for an agent        |
| **POST**   | [<mark style="color:$primary;">`/agent/obo/roles`</mark>](#post-agent-obo-roles)                | Create a vended role for an agent    |
| **DELETE** | [<mark style="color:$primary;">`/agent/obo/roles/{id}`</mark>](#delete-agent-obo-roles-id)      | Delete all vended roles for an agent |
| **GET**    | [<mark style="color:$primary;">`/agent/obo/roles/{id}`</mark>](#get-agent-obo-roles-id)         | View the status of an agent          |

## <mark style="color:green;">`GET`</mark> `/agent/{agentId}/activity`

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

**Required Immuta permission**: `USER_ADMIN`

```bash
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

```json
{
  "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"]
}
```

## <mark style="color:green;">`POST`</mark> `/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

```bash
curl -X POST "https://your.immuta.url.com/agent/obo/roles" \
     -H "Authorization: Bearer 09a0ffd7512f4aeeb66c09f3111c436c" \
     -H 'Content-Type: application/json' \
     -d '{
     "userid": "taylor@immuta.com",
     "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             | -              | <ul><li><code>Snowflake</code></li><li><code>Databricks</code></li></ul> |
| **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](#vended-role-object-attributes).

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

## <mark style="color:green;">`DELETE`</mark> `/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

```bash
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

## <mark style="color:$success;">`GET`</mark> `/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

```bash
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).

## Vended role object attributes

<table><thead><tr><th width="374">Attribute</th><th>Description</th></tr></thead><tbody><tr><td><strong>id</strong> <code>string</code></td><td>The unique identifier of the vended role.</td></tr><tr><td><strong>roles</strong> <code>object</code></td><td>Objects for each vended role created for each platform.</td></tr><tr><td>roles.{<strong>technology</strong>} <code>object</code></td><td>An object for the vended role created for the specific platform.</td></tr><tr><td>roles.{technology}.<strong>roleName</strong> <code>string</code></td><td>The name of the vended role created for that specific platform.</td></tr><tr><td>roles.{technology}.<strong>status</strong> <code>string</code></td><td>The status of the vended role created for that specific platform. Options include <code>CREATING</code>, <code>READY</code>, <code>FAILED</code>, <code>EXPIRED</code>, and <code>DROPPED</code>.</td></tr><tr><td><strong>expiresAt</strong> <code>timestamp</code></td><td>The time that the vended roles for the agent will automatically expire.</td></tr></tbody></table>


---

# Agent Instructions: 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/immuta-v1-api/configure-your-instance-of-immuta/manage-agent-identities.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.