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

# Bindings

> Grant an agent access to a toolkit and its connected account.

A binding tells Hexel which connected account to use when an agent calls a toolkit. Without a binding, the agent can't use the tools — it's the link between "this agent" and "these credentials for this provider." For example, binding your support agent to your team's Gmail connected account lets it send replies on behalf of that mailbox.

A binding connects an agent to a toolkit using a specific connected account's credentials. Without a binding, an agent cannot use a toolkit's tools.

## Key concepts

| Term                  | Meaning                                                                     |
| --------------------- | --------------------------------------------------------------------------- |
| **Binding**           | A mapping: agent + toolkit + connected account.                             |
| **Connected account** | The credential the binding draws on.                                        |
| **Resolution**        | The gateway automatically selecting the right credential at execution time. |

## How it works

```
Connected account + Agent + Toolkit → Binding → Agent can execute the toolkit's tools
```

When an agent executes a tool, the gateway resolves credentials from the agent's bindings. You control which toolkits each agent is bound to; the platform handles credential selection.

## Getting started

```bash theme={"dark"}
# Create a binding
curl -X POST https://api.hexelstudio.com/tools/v1/bindings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "toolkit": "GMAIL",
    "connected_account_id": "YOUR_CONNECTED_ACCOUNT_ID"
  }'

# List bindings
curl https://api.hexelstudio.com/tools/v1/bindings \
  -H "Authorization: Bearer $TOKEN"
```

## Errors

| HTTP  | `code`            | When                                                      |
| ----- | ----------------- | --------------------------------------------------------- |
| `400` | `INVALID_REQUEST` | Missing `agent_id`, `toolkit`, or `connected_account_id`. |
| `404` | —                 | The agent, toolkit, or connected account doesn't exist.   |
| `403` | —                 | Not permitted to manage bindings in this workspace.       |

## Security

| Concern             | Detail                                                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Credential handling | At execution time the gateway resolves credentials from the binding automatically. Your code passes inputs, never secrets. |
| Scoping             | Bindings are scoped to your organization, workspace, and environment.                                                      |
| Least privilege     | Grant each agent only the toolkits it actively needs. Unused bindings expand the blast radius if an agent is compromised.  |

## Common mistakes

* **Binding before connecting an account.** Connect the provider account first.
* **Over-binding.** Bind only the toolkits an agent actually needs.

## Best practices

* Give each agent the minimum set of toolkit bindings.
* Reuse one connected account across multiple agents.
* Review bindings when an agent's scope changes.

## Related pages

<CardGroup cols={2}>
  <Card title="Connected Accounts" icon="link" href="/docs/tool-gateway/connected-accounts">
    The credentials a binding uses.
  </Card>

  <Card title="Executing Tools" icon="play" href="/docs/tool-gateway/execution">
    Run tools an agent is bound to.
  </Card>

  <Card title="Workspace Groups" icon="lock" href="/docs/tool-gateway/workspace-groups">
    Limit which tools can be bound.
  </Card>

  <Card title="Tools (concept)" icon="plug" href="/docs/concepts/tools">
    The model behind bindings.
  </Card>
</CardGroup>