# Key info

> GET /key のリファレンスです。キー自体で、そのキーの組織、プロジェクト、ステータス、支出上限、有効期限、支出額を照会します。エラーボディは {message, code} の形式で、拒否されるキーはすべて 401 を受け取ります。

Source: https://kiln.bricksum.com/docs/ja/api-reference/key

`GET https://api.bricksum.com/v1/key`

呼び出しに使った API キーの組織、プロジェクト、ステータス、支出上限、有効期限、これまでの支出額を返します。コンソールのアカウントがなくてもキーを確認できる方法で、キーを持つチームメンバーが自分のキーを照会できます。平文のキーとそのハッシュはレスポンスに含まれません。

支出上限と月間予算の動作については [使用量と課金](https://kiln.bricksum.com/docs/ja/usage-billing) ページで説明しています。

Base URL、ほかのエンドポイント、共通の制限は [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページにあります。

## 認証

API キー自体を Bearer トークンとして送信します（Authorization: Bearer sk-bk-your-key）。このルートの識別情報はキーなので、コンソールのセッショントークンは受け付けません。このエンドポイントは推論ゲートウェイには属しません。Kiln API が直接処理し、キーをハッシュで照会して、有効なキーとして解決できないリクエストには 401 を返します。

## リクエスト

| ステータス | 説明 |
| --- | --- |
| 対応 | ゲートウェイが処理するか、公開済みの実測で動作を確認した項目です。 |
| 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| 無視 | 200 で受け付けられますが、適用されません。レスポンスのその他の部分は通常どおりです。 |
| 非対応 | エラーで拒否されるか、説明に記載したモデルでは動作しません。 |

| フィールド | 型 | 必須 | デフォルト | ステータス | 説明 |
| --- | --- | --- | --- | --- | --- |
| `Authorization` | header | 必須 |  | 対応 | API キーを含む Bearer トークンです（例：Authorization: Bearer sk-bk-your-key）。照会の前にキーの接頭辞と長さを検査するため、コンソールのセッショントークン（JWT）は 401（unauthorized）で拒否されます。 |
| `x-api-key` | header |  |  | 非対応 | このルートでは読み取りません。x-api-key だけを送ったリクエストは、値が有効なキーであっても 401（unauthorized）で拒否されます。Authorization を使用してください。 |
| `x-org-id` | header |  |  | 無視 | 識別ヘッダーの x-org-id、x-project-id、x-api-key-id は、このルートではゲートウェイが取り除きます。レスポンスの組織とプロジェクトは、ヘッダーではなくキーから決まります。 |
| `query string` | string |  |  | 無視 | このエンドポイントはパラメータを受け取りません。クエリ文字列は受け付けられますが、レスポンスには影響しません。 |

Authorization ヘッダーのキーが照会対象を決めます。ほかに送るものはありません。

## レスポンスボディ

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `id` | string | キー ID（UUID）です。コンソールのキー一覧にも同じ ID が表示されます。 |
| `org_id` | string | キーが属する組織の ID です。このキーの使用量はその組織に課金されます。 |
| `project_id` | string | キーが属するプロジェクトの ID です。 |
| `name` | string | コンソールでキーに付けた名前です。 |
| `prefix` | string | キーの接頭辞（sk-bk-）です。すべてのキーで同じ値です。 |
| `last4` | string | キーの末尾 4 文字です。一覧でキーを見分けるために使います。キー全体は作成直後に 1 度だけ表示され、その後は取得できません。 |
| `status` | string | キーのステータスです。成功したレスポンスには "active" が入ります。停止または失効したキーは、代わりに 401 を受け取ります。 |
| `spend_limit_usd` | number \| null | このキーの支出上限で、単位は USD です。null の場合、キー自体の上限はありません。上限に達すると、このキーでの推論リクエストは 402 で拒否されます。 |
| `expires_at` | string \| null | 有効期限で、RFC 3339 形式のタイムスタンプです。期限がない場合は null です。その時刻以降、このエンドポイントでも推論エンドポイントでもキーは 401 を受け取ります。 |
| `usage_usd` | number | このキーに記録された支出額で、単位は USD です。キーの usage イベントを合計した値で、支出上限はこの値と比較されます。 |
| `last_used_at` | string \| null | ゲートウェイがこのキーを最後に受け付けた時刻で、RFC 3339 形式です。使用履歴がない場合は null です。ゲートウェイがリクエスト処理の外で記録するため、直前の呼び出しはまだ反映されていないことがあります。 |
| `created_at` | string | キーを作成した時刻で、RFC 3339 形式です。 |

## エラー

このエンドポイントは推論ゲートウェイではなく Kiln API が処理するため、エラーボディは {"error": {"message", "code"}} の形式です。type と param のフィールドはなく、error.code は unauthorized のような短い文字列です。メッセージの文言ではなく、HTTP ステータスと error.code で分岐してください。

| ステータス | error.code | 原因 | 対処 |
| --- | --- | --- | --- |
| 401 | `unauthorized` | Authorization ヘッダーがない、Bearer トークンではない、または値が API キーの形式ではありません。コンソールのセッショントークンもこの場合に当たります。メッセージは API key required です。 | コンソールで作成した API キーを Authorization: Bearer で送信してください。 |
| 401 | `unauthorized` | キーが登録されていない、有効な状態ではない（停止または失効）、または有効期限を過ぎています。3 つのいずれの場合も invalid API key というメッセージで同じ 401 を返すため、レスポンスからはどの場合かは分かりません。 | コンソールでキーのステータスと有効期限を確認するか、新しいキーを作成してください。 |
| 429 |  | このルートに適用される共通のゲートウェイ上限です。組織ごとではなく全呼び出し元を合算して数えます。ゲートウェイ自身が生成するレスポンスのため、上記のエラー形式には従わず、ボディがないこともあります。 | 少し待ってから再試行してください。ボディをパースせず、ステータスだけで分岐してください。 |
| 500 | `internal` | キーストアを読み取れませんでした。メッセージは internal error です。 | 少し待ってから再試行し、ステータスページを確認してください。 |

すべてのステータスコードは [エラー](https://kiln.bricksum.com/docs/ja/errors) ページにあります。

## 制限

- 課金：課金されません。このエンドポイントは推論を実行しないため、usage イベントを発行せず、usage_usd も変わりません。
- 範囲：レスポンスは Authorization ヘッダーのキー 1 件だけを説明します。この認証方法で組織のキー一覧を取得するエンドポイントはありません。
- レート制限：ゲートウェイはこのルートに共通の上限を適用し、組織ごとではなく全呼び出し元を合算して数えます。この上限による 429 はゲートウェイが生成するため、ボディの形式は上記の説明とは異なります。
- このエンドポイントに対応する SDK はありません。OpenAI や Anthropic の API には含まれないため、各 SDK にメソッドがありません。HTTP クライアントで直接呼び出してください。

429 のヘッダーと再試行の方法は [レート制限](https://kiln.bricksum.com/docs/ja/rate-limits) ページにあります。

## サンプル

### リクエスト

**cURL**
```bash
curl https://api.bricksum.com/v1/key \
  -H "Authorization: Bearer $KILN_API_KEY"
```

### レスポンス

**200 OK**
```json
{
  "id": "6f1c2e7a-3c4d-4a10-9a2b-0f5c8d7e1234",
  "org_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
  "project_id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
  "name": "production",
  "prefix": "sk-bk-",
  "last4": "9f3c",
  "status": "active",
  "spend_limit_usd": 50,
  "expires_at": "2027-01-01T00:00:00Z",
  "usage_usd": 12.34,
  "last_used_at": "2026-09-18T07:21:03Z",
  "created_at": "2026-06-01T09:00:00Z"
}
```

**401 Unauthorized**
```json
{
  "error": {
    "message": "invalid API key",
    "code": "unauthorized"
  }
}
```