> ## 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.

# Workspace Groups

> Allow-list which tools are available within a workspace.

Workspace groups are allow-lists. If your organization wants to restrict which tools agents can use — say, only internal tools in production or only approved providers for a compliance-sensitive workspace — you define it here. By default everything is available; once you create a group, only the tools in that group remain accessible.

Workspace tool groups are allow-lists that control which tools can be used in a workspace. They let platform operators constrain the catalog to an approved set, independent of per-agent bindings.

## Key concepts

| Term                     | Meaning                                    |
| ------------------------ | ------------------------------------------ |
| **Workspace tool group** | An allow-list of tools for a workspace.    |
| **Group items**          | The specific tools or toolkits in a group. |
| **Default behavior**     | No groups defined = all tools allowed.     |

## How it works

```
No groups → all tools allowed
One or more groups → only listed tools allowed
```

Once you define a group, the workspace is restricted to the tools it lists. This is an explicit allow-list; tools not in any group become unavailable.

## Getting started

```bash theme={"dark"}
# Create a workspace tool group
curl -X POST https://api.hexelstudio.com/tools/v1/workspace-groups \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "approved-tools"}'

# Set the group's allow-list
curl -X PUT https://api.hexelstudio.com/tools/v1/workspace-groups/YOUR_GROUP_ID/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tools": ["SLACK_POST_MESSAGE", "GITHUB_CREATE_ISSUE"]}'
```

## Errors

| HTTP  | `code`            | When                                      |
| ----- | ----------------- | ----------------------------------------- |
| `400` | `INVALID_REQUEST` | Invalid group definition or item list.    |
| `404` | —                 | The workspace group doesn't exist.        |
| `403` | —                 | Not permitted to manage workspace groups. |

## Security

| Concern               | Detail                                                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Default behavior      | When no group exists, all tools are available in the workspace.                                                  |
| Allow-list activation | Creating the first group switches the workspace from open to restricted. Only listed tools are accessible.       |
| Management permission | Requires the appropriate RBAC permission. Platform operators control groups independently of per-agent bindings. |

<Warning>
  Adding a workspace group to a previously open workspace immediately restricts all agents in it. Verify the allow-list before creating the first group.
</Warning>

## Common mistakes

* **Creating a group without understanding the effect.** The first group switches the workspace from "all allowed" to "only listed." Review the list before adding one.
* **Forgetting to update the allow-list.** New tools agents need will not work until added to an active group.

## Best practices

* Decide deliberately whether a workspace should be open or allow-listed.
* Keep allow-lists current as teams adopt new tools.
* Use groups to enforce organizational tool policy centrally.

## Related pages

<CardGroup cols={2}>
  <Card title="Bindings" icon="link-horizontal" href="/docs/tool-gateway/bindings">
    Per-agent access within the allow-list.
  </Card>

  <Card title="Tool Catalog" icon="grip" href="/docs/tool-gateway/catalog">
    The tools you can allow.
  </Card>

  <Card title="Members & Roles" icon="users" href="/docs/iam/members-and-roles">
    Who can manage groups.
  </Card>

  <Card title="Tool Gateway" icon="plug" href="/docs/tool-gateway/overview">
    The full model.
  </Card>
</CardGroup>