> 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/developer-guides/api-intro/agentic-access-api/agentic-access-legacy.md).

# Agentic Access - Legacy

Vend ephemeral roles for your agents to access data on behalf of of a user

{% hint style="warning" %}
**Deprecation notice**: Support for this API has been deprecated.
{% endhint %}

When enabled, the legacy agentic access API is accessible on your Immuta tenant. Authentication must be done using an [agent API key](/SaaS/agentic-data-access/manage-agents.md#api-key-legacy-method).

## Endpoints and methods

| Method     | Endpoint                                                                                   | Description                          |
| ---------- | ------------------------------------------------------------------------------------------ | ------------------------------------ |
| **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;">`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",
     "iamid": "bim"
     }'
```

### Body parameters

| Parameter              | Description                                                                                                                                                                                                                                                                                                                                                                                            | Required or optional | Default values | Accepted values                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | -------------- | ------------------------------------------------------------------------ |
| **userid** `string`    | <p>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.<br><br>If the <code>userid</code> exists more than once in Immuta (such as a local and SSO user), the endpoint will respond with an error.</p> | 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 automatically expires.                                                                                                                                                                                                                                                                                                                               | Optional             | `1h`           | Accepted pattern: `^(\d+)(m\|h)$`                                        |
| **iamid** `string`     | The unique identifier of the identity provider that the human user account belongs to. Provide this parameter if the user belongs to more than one identity provider.                                                                                                                                                                                                                                  | Optional             | -              | -                                                                        |

### Response

Returns a [vended role object](#vended-role-object-attributes).

```json
{
  "id": "019fcd26-e9f8-746f-a174-fdebc0e643cf",
  "roles": {
    "Snowflake": {
      "roleName": "IMMUTA_VENDED_3f2504e0-4f89-11d3-9a0c-0305e82c3301",
      "status": "READY"
    },
    "Databricks": {
      "roleName": "IMMUTA_VENDED_9b2504e0-4f89-11d3-9a0c-0305e82c3302",
      "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 assinged to the role vending transaction.</td></tr><tr><td><strong>roles</strong> <code>object</code></td><td>Objects for each vended role created for each platform. A role will be vended for each connection associated with the supplied technology.</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
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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.immuta.com/SaaS/developer-guides/api-intro/agentic-access-api/agentic-access-legacy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.