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

# Vaults で認証する

> シークレットを安全に保存し、Agent Session に注入する。

Agent はサードパーティサービス — GitHub、Jira、データベース、自前 MCP サーバーなど — にアクセスする必要があることがしばしばあります。Vaults はセキュアな認証情報の預け先を提供し、トークンを当社に保管していただき、Session 実行時に必要に応じて注入します。コードへのハードコーディングは不要です。

## コアコンセプト

| 概念          | 説明                                                                       |
| ----------- | ------------------------------------------------------------------------ |
| Vault       | 複数の Credential を保持できる認証情報コンテナ                                            |
| Credential  | 具体的な MCP サーバー URL にバインドされた個別の認証情報                                        |
| `auth.type` | Credential の認証タイプ：`static_bearer`、`mcp_oauth`、または `environment_variable` |
| `vault_ids` | Session 作成時に参照する Vault ID のリスト                                           |

## セキュリティ

* `access_token` は API レスポンスで**決して**返却されません。
* `token`、`refresh_token`、`client_secret`、`secret_value` などのその他のシークレットも返却されません。
* 認証情報はサーバー側で暗号化保管されます。
* 関連付けられた Session のみが実行時に認証情報内容を読み取れます。

## エンドツーエンドフロー

<Steps>
  <Step title="Vault を作成する">
    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/vaults \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "display_name": "My GitHub credentials",
        "metadata": {}
      }'
    ```

    レスポンス例:

    ```json theme={null}
    {
      "id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
      "type": "vault",
      "display_name": "My GitHub credentials",
      "credentials": [],
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-05-18T08:00:00Z",
      "updated_at": "2026-05-18T08:00:00Z"
    }
    ```
  </Step>

  <Step title="Credential を追加する">
    ネストされた `auth` を指定して Vault に Credential を追加します。

    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/vaults/vault_019e5cdb9c3f71c3b6505eba937a40b4/credentials \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "auth": {
          "type": "static_bearer",
          "mcp_server_url": "https://jira.example.com/mcp",
          "token": "jira_token_xxxxxxxx"
        }
      }'
    ```

    レスポンスは `type: "vault_credential"` とサニタイズされた `auth` オブジェクトを返します。シークレットの値は含まれません。
  </Step>

  <Step title="Session で使用する">
    Session 作成時に `vault_ids` で Vault を関連付けます。

    ```bash theme={null}
    curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
      -H "Authorization: Bearer $QODER_PAT" \
      -H "Content-Type: application/json" \
      -d '{
        "agent": "agent_xxx",
        "vault_ids": ["vault_019e5cdb9c3f71c3b6505eba937a40b4"]
      }'
    ```

    Session 実行時、Agent は Vault に含まれるすべての Credential のアクセス権を自動的に取得し、対応する MCP サーバーへの認証に利用します。
  </Step>
</Steps>

## パラメータ

| パラメータ                 | 型      | 必須                   | 説明                                                     |
| --------------------- | ------ | -------------------- | ------------------------------------------------------ |
| `display_name`        | string | はい                   | Vault の表示名                                             |
| `metadata`            | object | いいえ                  | カスタムメタデータ                                              |
| `auth.type`           | string | Credential では必須      | `static_bearer`、`mcp_oauth`、または `environment_variable` |
| `auth.mcp_server_url` | string | MCP Credential では必須  | MCP サーバー URL                                           |
| `auth.token`          | string | `static_bearer` では必須 | Bearer トークンの値。書き込み専用                                   |

## よくある質問

**Q: Credential のトークンを更新できますか?** A: 旧 Credential を削除し、新たに作成することでローテーションします。

**Q: 1 つの Session に Vault を何個関連付けられますか?** A: ハードリミットはありませんが、整理のためサービス単位でグループ化してください。

**Q: トークンが漏洩しました。どうすればよいですか?** A: 直ちに該当 Credential を削除し、サードパーティプラットフォームでトークンを失効させたうえで、新しい Credential を作成してください。

**Q: 保管したトークンを参照できますか?** A: できません。セキュリティ上、認証情報のシークレットは書き込み専用であり、削除して再作成することのみ可能です。

<Note>
  環境ごと (開発/本番) に独立した Vault を使用し、認証情報の混在を避けてください。
</Note>

## 次のステップ

<CardGroup cols={2}>
  <Card title="Session の開始" icon="play" href="/ja/cloud-agents/sessions">
    環境に対して Agent を実行する。
  </Card>

  <Card title="Agent の定義" icon="user-gear" href="/ja/cloud-agents/define-agent">
    Agent の構成を確認する。
  </Card>

  <Card title="永続メモリの構築" icon="brain" href="/ja/cloud-agents/memory-stores">
    Session をまたいだ永続メモリを Agent に与える。
  </Card>

  <Card title="クラウド環境" icon="server" href="/ja/cloud-agents/environments">
    ランタイムをカスタマイズする。
  </Card>
</CardGroup>