> 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/agent.md).

# Agent

Agent-authenticated endpoints

## Create vended roles

> Creates vended roles on-behalf-of a user across the requested platforms. Roles are provisioned asynchronously and torn down when the TTL expires.

```json
{"openapi":"3.0.0","info":{"title":"Comply API","version":"1.0"},"tags":[{"name":"Agent","description":"Agent-authenticated endpoints"}],"paths":{"/agents/roles":{"post":{"description":"Creates vended roles on-behalf-of a user across the requested platforms. Roles are provisioned asynchronously and torn down when the TTL expires.","operationId":"createVendedRoles","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVendedRolesBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendedRolesResponseDto"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AugmentedZodDto"}}}}},"summary":"Create vended roles","tags":["Agent"]}}},"components":{"schemas":{"CreateVendedRolesBodyDto":{"type":"object","properties":{"username":{"description":"Username of the user to vend roles on behalf of","type":"string","minLength":1},"iamId":{"description":"Identity provider to disambiguate the user with, when the username matches more than one identity","type":"string","minLength":1},"ttl":{"description":"How long the vended roles remain valid, in milliseconds. Between 1m and 24h. Defaults to 1h","default":3600000},"platforms":{"description":"Platforms to vend roles on","type":"array","minItems":1,"items":{"type":"object","properties":{"technology":{"description":"Data platform to vend roles on","type":"string","enum":["Snowflake","Databricks"]},"connectionKeys":{"description":"Restricts vending to these connections. Omit to vend on every connection for the platform. Required with exactly one key for Databricks.","type":"array","minItems":1,"items":{"type":"string","minLength":1}}},"required":["technology"]}}},"required":["username","platforms"]},"VendedRolesResponseDto":{"type":"object","properties":{"requestId":{"description":"Identifier of the vending request, used to fetch or tear down the roles","type":"string","format":"uuid"},"createdAt":{"description":"When the roles were requested, as an ISO 8601 timestamp","type":"string","format":"date-time"},"expiresAt":{"description":"When the roles are torn down, as an ISO 8601 timestamp","type":"string","format":"date-time"},"roles":{"description":"Roles vended for this request, one per platform connection","type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"description":"Unique identifier of the vended role","type":"string","format":"uuid"},"name":{"description":"Name of the role as created on the platform","type":"string"},"technology":{"description":"Data platform the role was vended on","type":"string","enum":["Snowflake"]},"connectionKey":{"description":"Connection the role was vended against","type":"string"},"status":{"description":"Provisioning state of the role","type":"string","enum":["CREATING","READY","FAILED","DROPPED","ABANDONED"]},"metadata":{"description":"Snowflake-native details of the granted role, or null until the role is created","type":"object","properties":{"roleName":{"description":"Name of the granted Snowflake role","type":"string"}},"required":["roleName"],"nullable":true}},"required":["id","name","technology","connectionKey","status","metadata"]},{"type":"object","properties":{"id":{"description":"Unique identifier of the vended role","type":"string","format":"uuid"},"name":{"description":"Name of the role as created on the platform","type":"string"},"technology":{"description":"Data platform the role was vended on","type":"string","enum":["Databricks"]},"connectionKey":{"description":"Connection the role was vended against","type":"string"},"status":{"description":"Provisioning state of the role","type":"string","enum":["CREATING","READY","FAILED","DROPPED","ABANDONED"]},"metadata":{"description":"Databricks-native details of the granted group, or null until the group is created","type":"object","properties":{"groupName":{"description":"Name of the granted Databricks group","type":"string"},"groupId":{"description":"Identifier of the granted Databricks group","type":"string"}},"required":["groupName","groupId"],"nullable":true}},"required":["id","name","technology","connectionKey","status","metadata"]}]}}},"required":["requestId","createdAt","expiresAt","roles"]},"AugmentedZodDto":{"type":"object","properties":{"statusCode":{"description":"HTTP status code of the failure","type":"number"},"message":{"description":"Human-readable description of what went wrong","type":"string"},"error":{"description":"Short name for the error class, e.g. `Bad Request`","type":"string"}},"required":["statusCode","message"]}}}}
```

## Get vended roles

> Returns the roles vended for a request, including their current provisioning status.

```json
{"openapi":"3.0.0","info":{"title":"Comply API","version":"1.0"},"tags":[{"name":"Agent","description":"Agent-authenticated endpoints"}],"paths":{"/agents/roles/{id}":{"get":{"description":"Returns the roles vended for a request, including their current provisioning status.","operationId":"getVendedRoles","parameters":[{"name":"id","required":true,"in":"path","description":"Identifier of the vending request, as returned when the roles were created","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VendedRolesResponseDto"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AugmentedZodDto"}}}}},"summary":"Get vended roles","tags":["Agent"]}}},"components":{"schemas":{"VendedRolesResponseDto":{"type":"object","properties":{"requestId":{"description":"Identifier of the vending request, used to fetch or tear down the roles","type":"string","format":"uuid"},"createdAt":{"description":"When the roles were requested, as an ISO 8601 timestamp","type":"string","format":"date-time"},"expiresAt":{"description":"When the roles are torn down, as an ISO 8601 timestamp","type":"string","format":"date-time"},"roles":{"description":"Roles vended for this request, one per platform connection","type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"description":"Unique identifier of the vended role","type":"string","format":"uuid"},"name":{"description":"Name of the role as created on the platform","type":"string"},"technology":{"description":"Data platform the role was vended on","type":"string","enum":["Snowflake"]},"connectionKey":{"description":"Connection the role was vended against","type":"string"},"status":{"description":"Provisioning state of the role","type":"string","enum":["CREATING","READY","FAILED","DROPPED","ABANDONED"]},"metadata":{"description":"Snowflake-native details of the granted role, or null until the role is created","type":"object","properties":{"roleName":{"description":"Name of the granted Snowflake role","type":"string"}},"required":["roleName"],"nullable":true}},"required":["id","name","technology","connectionKey","status","metadata"]},{"type":"object","properties":{"id":{"description":"Unique identifier of the vended role","type":"string","format":"uuid"},"name":{"description":"Name of the role as created on the platform","type":"string"},"technology":{"description":"Data platform the role was vended on","type":"string","enum":["Databricks"]},"connectionKey":{"description":"Connection the role was vended against","type":"string"},"status":{"description":"Provisioning state of the role","type":"string","enum":["CREATING","READY","FAILED","DROPPED","ABANDONED"]},"metadata":{"description":"Databricks-native details of the granted group, or null until the group is created","type":"object","properties":{"groupName":{"description":"Name of the granted Databricks group","type":"string"},"groupId":{"description":"Identifier of the granted Databricks group","type":"string"}},"required":["groupName","groupId"],"nullable":true}},"required":["id","name","technology","connectionKey","status","metadata"]}]}}},"required":["requestId","createdAt","expiresAt","roles"]},"AugmentedZodDto":{"type":"object","properties":{"statusCode":{"description":"HTTP status code of the failure","type":"number"},"message":{"description":"Human-readable description of what went wrong","type":"string"},"error":{"description":"Short name for the error class, e.g. `Bad Request`","type":"string"}},"required":["statusCode","message"]}}}}
```

## Tear down vended roles

> Initiates teardown of the roles vended for a request, ahead of their TTL. Teardown proceeds asynchronously.

```json
{"openapi":"3.0.0","info":{"title":"Comply API","version":"1.0"},"tags":[{"name":"Agent","description":"Agent-authenticated endpoints"}],"paths":{"/agents/roles/{id}":{"delete":{"description":"Initiates teardown of the roles vended for a request, ahead of their TTL. Teardown proceeds asynchronously.","operationId":"deleteVendedRoles","parameters":[{"name":"id","required":true,"in":"path","description":"Identifier of the vending request, as returned when the roles were created","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":""},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AugmentedZodDto"}}}}},"summary":"Tear down vended roles","tags":["Agent"]}}},"components":{"schemas":{"AugmentedZodDto":{"type":"object","properties":{"statusCode":{"description":"HTTP status code of the failure","type":"number"},"message":{"description":"Human-readable description of what went wrong","type":"string"},"error":{"description":"Short name for the error class, e.g. `Bad Request`","type":"string"}},"required":["statusCode","message"]}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.