> 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/api-integration/endpoint-behaviors/tool-trust-api.md).

# Hook 工具還原授權 API

以組織層 API 管理哪些工具或 MCP 連接器可以收到 Hook 還原後的真實參數。

使用敏感資料代碼化 Hook 時，工具原本可能只收到代碼。組織可以授權指定工具或 MCP 連接器，讓它們在工具參數中收到還原後的真實值。這項授權不是全域解除遮罩，也不會把所有工具一併變成可信任。

例如，組織需要讓自己的訂單查詢工具收到真實查詢值，但其他工具仍只拿到代碼。擁有者可以只授權訂單查詢工具；不再需要時再撤銷，下一則訊息重新組裝工具後套用更新的授權。

## 權限與範圍 <a href="#permissions-and-scope" id="permissions-and-scope"></a>

* 在職組織成員可以讀取授權清單；只有組織擁有者可以新增或撤銷。
* 可授權本組織的非全域 API、Function、MCP 工具，或本組織的 MCP 連接器。連接器授權涵蓋透過該連接器提供的子工具。
* 全域工具不能透過本 API 授權。不能授權其他組織的工具或連接器。
* 授權範圍由伺服器固定為 `resolve_aliases`，不要在請求中自行設定 `scope`。

這是組織層的授權，不是某一個 Agent 專用的設定。請只授權確實需要接收真實參數的目標。

## 讀取授權清單 <a href="#list-trusts" id="list-trusts"></a>

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

回應為不分頁的陣列，每筆包含：

| 欄位          | 說明                                                       |
| ----------- | -------------------------------------------------------- |
| `id`        | 授權 ID；撤銷時使用這個 ID，而不是工具 ID                                |
| `tool`      | 工具摘要：`id`、`name`、`displayName`、`toolType`；連接器授權時為 `null` |
| `connector` | 連接器摘要：`id`、`displayName`；工具授權時為 `null`                   |
| `scope`     | `resolve_aliases`                                        |
| `createdAt` | 建立時間                                                     |

## 授權一個目標 <a href="#grant-trust" id="grant-trust"></a>

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

授權工具：

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

授權連接器：

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

`tool` 與 `connector` 必須二選一；不要兩者都填，也不要兩者都省略。成功回 `201`，回應與清單中的單筆授權相同。

## 撤銷與生效時機 <a href="#revoke-and-effect" id="revoke-and-effect"></a>

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

成功回 `204`，該授權會從清單移除。既有授權也會出現在同一份清單，可以透過 API 撤銷；每次授權與撤銷都會留下操作者的稽核紀錄。

{% hint style="warning" %}
工具會在組裝時讀取授權清單。授權或撤銷後，請在下一則訊息確認新行為；不要假設正在生成的同一輪回覆會在中途立即切換。還原只作用於工具參數中的代碼，不是把對話內容全面改回真實值。
{% endhint %}

## 處理拒絕與輸入錯誤 <a href="#handle-errors" id="handle-errors"></a>

非擁有者新增或撤銷會被拒絕；跨組織網址也會被拒絕，跨組織的授權 ID 不會透過撤銷入口外露。

下列驗證失敗回 `400`。錯誤回應格式請參考 [API 共通規範](https://docs.maiagent.ai/tech/api-integration/api-conventions.md)：

| 錯誤代碼                        | 修正方式                             |
| --------------------------- | -------------------------------- |
| `exactly_one_target`        | 只提供 `tool` 或 `connector` 其中一個    |
| `not_in_organization`       | 使用本組織的工具或連接器                     |
| `global_tool_not_grantable` | 不透過本 API 授權全域工具                  |
| `tool_type_not_resolvable`  | 改用可接收還原參數的 API、Function 或 MCP 工具 |
| `already_trusted`           | 目標已授權，讀取現有清單即可                   |
| `unknown_field`             | 移除未支援的輸入欄位，例如 `scope`            |

工具本身的定義與認證方式，請參考 [API 工具工程指南](https://docs.maiagent.ai/tech/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/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.
