> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/api-integration/endpoint-behaviors/tool-trust-api.md).

# Hook Tool Trust Restoration API

Use the organization-level API to manage which tools or MCP connectors can receive real parameter values restored by a Hook.

When you use a Hook to tokenize sensitive data, tools may initially receive only tokens. An organization can authorize specific tools or MCP connectors to receive the restored real values in tool parameters. This authorization does not globally unmask data or make all tools trusted.

For example, an organization may need its own order lookup tool to receive real query values while other tools continue to receive only tokens. The owner can authorize just the order lookup tool and revoke that authorization when it is no longer needed. The updated authorization takes effect when tools are assembled again for the next message.

## Permissions and Scope <a href="#permissions-and-scope" id="permissions-and-scope"></a>

* Active organization members can read the authorization list; only the organization owner can grant or revoke authorization.
* You can authorize non-global API, Function, and MCP tools belonging to your organization, or your organization's MCP connectors. Authorizing a connector covers the child tools provided through that connector.
* Global tools cannot be authorized through this API. You cannot authorize tools or connectors belonging to another organization.
* The server fixes the authorization scope to `resolve_aliases`. Do not set `scope` in the request.

This authorization applies to the organization, rather than to a specific Agent. Authorize only targets that actually need to receive real parameter values.

## Read the Authorization List <a href="#list-trusts" id="list-trusts"></a>

`GET /api/v1/organizations/<organization-id>/tool-trusts/`

The response is an unpaginated array. Each entry contains:

| Field       | Description                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------- |
| `id`        | Authorization ID; use this ID, rather than the tool ID, when revoking authorization           |
| `tool`      | Tool summary: `id`, `name`, `displayName`, and `toolType`; `null` for connector authorization |
| `connector` | Connector summary: `id` and `displayName`; `null` for tool authorization                      |
| `scope`     | `resolve_aliases`                                                                             |
| `createdAt` | Creation time                                                                                 |

## Authorize a Target <a href="#grant-trust" id="grant-trust"></a>

`POST /api/v1/organizations/<organization-id>/tool-trusts/`

Authorize a tool:

```json
{"tool": "<tool-id>"}
```

Authorize a connector:

```json
{"connector": "<connector-id>"}
```

Provide exactly one of `tool` or `connector`; do not provide both or omit both. A successful request returns `201`, with the same response structure as a single authorization entry in the list.

## Revocation and When Changes Take Effect <a href="#revoke-and-effect" id="revoke-and-effect"></a>

`DELETE /api/v1/organizations/<organization-id>/tool-trusts/<trust-id>/`

A successful request returns `204` and removes the authorization from the list. Existing authorizations also appear in the same list and can be revoked through the API. Each grant or revocation records the operator in the audit log.

{% hint style="warning" %}
Tools read the authorization list when they are assembled. After granting or revoking authorization, verify the new behavior with the next message; do not assume a response currently being generated will switch behavior immediately midway through. Restoration applies only to tokens in tool parameters; it does not restore all conversation content to real values.
{% endhint %}

## Handle Access Denials and Input Errors <a href="#handle-errors" id="handle-errors"></a>

Requests to grant or revoke authorization from anyone other than the owner are denied. Requests using another organization's URL are also denied, and the revocation endpoint does not expose authorization IDs belonging to other organizations.

The following validation failures return `400`. For the error response format, see [API Conventions](https://docs.maiagent.ai/tech/en/api-integration/api-conventions.md):

| Error Code                  | How to Fix                                                             |
| --------------------------- | ---------------------------------------------------------------------- |
| `exactly_one_target`        | Provide only one of `tool` or `connector`                              |
| `not_in_organization`       | Use a tool or connector belonging to your organization                 |
| `global_tool_not_grantable` | Do not authorize global tools through this API                         |
| `tool_type_not_resolvable`  | Use an API, Function, or MCP tool that can receive restored parameters |
| `already_trusted`           | The target is already authorized; read the existing list               |
| `unknown_field`             | Remove unsupported input fields, such as `scope`                       |

For tool definitions and authentication methods, see the [API Tool Engineering Guide](https://docs.maiagent.ai/tech/en/api-integration/api-tool-engineering-guide.md).


---

# 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://docs.maiagent.ai/tech/en/api-integration/endpoint-behaviors/tool-trust-api.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.
