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

# APIキー管理

> Jinba Toolbox APIの認証用APIキーの作成、確認、失効

APIキーは、Jinba Toolbox APIへのリクエストを認証します。ツールの実行、ToolSetの管理、実行履歴の参照など、すべてのAPI呼び出しに有効なAPIキーが必要です。キーは組織にスコープされ、その組織のリソースへのアクセスを提供します。

## APIキーの仕組み

```
Authorization: Bearer jtb_xxxxxxxxxxxx
```

すべてのAPIキーは`jtb_`プレフィックスを使用します。キーを作成すると、完全なキー値は一度だけ表示されます。以降は、識別用にマスクされたプレフィックスのみがコンソールに表示されます。

APIキーは作成された組織に紐付けられます。組織AのキーでOrganization Bのリソースにアクセスすることはできません（公開ツールの実行を除く。公開ツールは有効なキーであればどれでも実行可能です）。

## APIキーの作成

<Steps>
  <Step title="API Keysに移動">
    組織のサイドバーで**API Keys**を開きます。既存のキーの一覧が表示されます（ある場合）。
  </Step>

  <Step title="キーの作成をクリック">
    ページ上部の**Create API Key**ボタンをクリックします。モーダルが表示されます。
  </Step>

  <Step title="名前を入力">
    キーの用途を識別するための分かりやすい名前を付けます（例：「Production Backend」、「CI/CD Pipeline」、「Local Development」）。この名前は参照用であり、キーの権限には影響しません。
  </Step>

  <Step title="キーをコピー">
    **Create Key**をクリックすると、完全なAPIキーが表示されます。すぐにコピーして安全な場所に保存してください。

    <Warning>
      完全なAPIキーは作成時に一度だけ表示されます。紛失した場合は、新しいキーを作成する必要があります。
    </Warning>
  </Step>

  <Step title="完了">
    **Done**をクリックしてモーダルを閉じます。新しいキーが一覧に表示され、名前、マスクされたプレフィックス、作成者、作成日、最終使用日が確認できます。
  </Step>
</Steps>

## APIキー一覧

API Keysページには以下のカラムを持つテーブルが表示されます：

| カラム            | 説明                                  |
| -------------- | ----------------------------------- |
| **Name**       | キーに付けた説明的な名前                        |
| **Key Prefix** | 識別用のキーのマスクされたプレビュー（例：`jtb_abc1...`） |
| **Created By** | キーを作成したユーザー                         |
| **Created**    | キーが作成された日時                          |
| **Last Used**  | このキーで行われた最新のAPI呼び出しのタイムスタンプ         |

## APIキーの失効

キーを失効させるには、一覧のキーの横にある削除アクションをクリックします。確認ダイアログが表示されます。失効すると：

* キーは即座に無効化されます。
* このキーを使用するすべてのAPIリクエストは`401 Unauthorized`エラーを返します。
* この操作は永続的で元に戻すことはできません。

<Note>
  キーの失効は、過去の実行記録やデータには影響しません。そのキーを使用した将来のAPI呼び出しのみが防止されます。
</Note>

## 認証スコープ

APIキーは以下のスコープに基づいてアクセスを提供します：

<CardGroup cols={2}>
  <Card title="Read" icon="eye">
    ToolSet、ツール、バージョン、実行記録、その他の組織リソースの一覧表示と取得を行います。
  </Card>

  <Card title="Write" icon="pen">
    ToolSet、ツール、環境変数、その他のリソースの作成、更新、削除を行います。
  </Card>

  <Card title="Execute" icon="play">
    ツールの実行と実行記録の作成を行います。API実行とMCPツールコールの両方に必要です。
  </Card>

  <Card title="Admin" icon="shield-halved">
    組織設定、メンバー、APIキーの管理を行います。完全な管理者アクセスです。
  </Card>
</CardGroup>

## APIキーの使用

### REST API

`Authorization`ヘッダーにキーを含めます：

```bash theme={null}
curl -X POST \
  https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/{slug}/tools/{toolSlug}/run \
  -H "Authorization: Bearer jtb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'
```

### TypeScript SDK

SDKクライアントの作成時にキーを渡します：

```typescript theme={null}
import { createClient } from "@jinba-toolbox/sdk";

const client = createClient({
  apiKey: process.env.JINBA_TR_API_KEY,
  organizationId: "your-org-id",
});

const result = await client.run("slack-tools", "post-message", {
  channel: "#general",
  text: "Hello from Jinba Toolbox!",
});
```

### MCP Endpoint

AIエージェントをToolSetのMCPエンドポイントに接続する際は、接続設定の一部としてAPIキーを提供します。MCPエンドポイントURLは、MCP Serverが有効になっている場合にToolSet詳細ページで確認できます。

## 個人キーと組織APIキー

Jinba Toolboxは2つのレベルのAPIキーをサポートしています：

| タイプ         | スコープ            | 場所                 |
| ----------- | --------------- | ------------------ |
| **組織APIキー** | 単一の組織のリソースにスコープ | 組織サイドバー > API Keys |
| **個人APIキー** | ユーザーのアカウントにスコープ | ダッシュボード > API Keys |

<Note>
  ほとんどのユースケースでは組織APIキーを推奨します。個人のユーザーアカウントに影響を与えることなく、管理、ローテーション、失効が容易です。
</Note>

## ベストプラクティス

* **分かりやすい名前を付ける** -- 用途と環境でキーに名前を付けます（例：「Production API Server」、「Staging CI」）。必要な場合にどのキーを失効させるべきか特定しやすくなります。
* **定期的にキーをローテーションする** -- 漏洩の影響を限定するために、定期的に新しいキーを作成し、古いキーを失効させます。
* **キーをソースコードにコミットしない** -- キーは環境変数またはシークレット管理ツールに保存します。
* **環境ごとに別々のキーを使用する** -- 開発、ステージング、本番環境ごとに個別のキーを作成します。
* **未使用のキーを失効させる** -- キーが不要になったら、すぐに失効させます。「Last Used」カラムを確認して、使用されていないキーを特定します。
* **組織キーを優先する** -- アプリケーション統合には、個人キーではなく組織スコープのキーを使用します。