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

# Hook ツールの信頼を復元する API

組織レベルの API を使用して、Hook によって復元された実際のパラメータ値を受け取れるツールや MCP コネクタを管理します。

機密データをトークン化する 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` が返り、レスポンスは一覧内の認可 1 件と同じ構造になります。

## 取り消しと反映のタイミング <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>

オーナー以外による認可の追加や取り消しは拒否されます。他の組織の URL を使用したリクエストも拒否され、取り消しエンドポイントから他の組織の認可 ID が公開されることはありません。

次の検証に失敗した場合は `400` が返ります。エラーレスポンスの形式については、[API 共通規約](https://docs.maiagent.ai/tech/ja/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/ja/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/ja/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.
