> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Grants API: Control Which Credentials Agents Use

> Attach and detach app connections and secrets for agents with the OneCLI API. Set per-tool allow and ask lists, and every change applies instantly.

A grant decides which credentials an agent may use. Connection grants can allow every tool or name tools to allow and tools that need approval, with optional resource scoping. Secret grants are all or nothing.

Writes take effect immediately, with no publish step. You can address a grant from the agent's side or the connection's side. To see what actually gets through after organization rules, use [Effective policy](https://onecli.sh/docs/api-reference/effective-policy). For the concepts, see [Agent access](https://onecli.sh/docs/guides/agent-access.md).

## Related guides

* [Agent access: grant credentials to agents](https://onecli.sh/docs/guides/agent-access.md)
* [Rules: organization policy on top of grants](https://onecli.sh/docs/guides/rules.md)

## Endpoints

| Endpoint | Method and path | What it does |
| - | - | - |
| [Get an agent's grants](https://onecli.sh/docs/api-reference/grants/get-an-agents-grants.md) | `GET /agents/{agentId}/grants` | Get everything granted to one agent: its app connections with per-tool lists and resource scoping, plus the secrets attached to it. |
| [Attach a connection to an agent](https://onecli.sh/docs/api-reference/grants/attach-a-connection-to-an-agent.md) | `PUT /agents/{agentId}/grants/connections/{connectionId}` | Attach an app connection to an agent with full access or custom allow and ask tool lists. |
| [Detach a connection from an agent](https://onecli.sh/docs/api-reference/grants/detach-a-connection-from-an-agent.md) | `DELETE /agents/{agentId}/grants/connections/{connectionId}` | Detach an app connection from an agent. |
| [Attach a secret to an agent](https://onecli.sh/docs/api-reference/grants/attach-a-secret-to-an-agent.md) | `PUT /agents/{agentId}/grants/secrets/{secretId}` | Attach a secret, such as an API key or LLM key, to an agent. |
| [Detach a secret from an agent](https://onecli.sh/docs/api-reference/grants/detach-a-secret-from-an-agent.md) | `DELETE /agents/{agentId}/grants/secrets/{secretId}` | Detach a secret from an agent. |
| [Get a connection's grants](https://onecli.sh/docs/api-reference/grants/get-a-connections-grants.md) | `GET /connections/{connectionId}/grants` | See which agents hold a grant for one connection and each agent's access level. |
| [Attach an agent to a connection](https://onecli.sh/docs/api-reference/grants/attach-an-agent-to-a-connection.md) | `PUT /connections/{connectionId}/grants/agents/{agentId}` | Attach an agent to a connection from the connection's side. |
| [Detach an agent from a connection](https://onecli.sh/docs/api-reference/grants/detach-an-agent-from-a-connection.md) | `DELETE /connections/{connectionId}/grants/agents/{agentId}` | Detach an agent from a connection, addressed from the connection's side. |

## Next steps

* [API overview](https://onecli.sh/docs/api-reference.md): base URLs, authentication, and pagination
* [Errors](https://onecli.sh/docs/api-reference/errors.md): status codes and the error format
* [Editions](https://onecli.sh/docs/api-reference/editions.md): which endpoints each edition serves


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.