# API Keys API

これらのエンドポイントを使用すると、コードからアカウントのAPIキーを管理できます。これらはすべて、呼び出し元アカウント自身のキーに対してのみ操作を行います。

キーには2種類あり、それぞれ異なるパスで管理されます。

- **メインキー** — **設定 → インテグレーション → APIキー** にある、フルアクセス権を持つ単一のキーです。マスクされたプレビューの確認、レート制限の使用状況のチェック、ローテーション、または取り消しを行うことができます。これらは以下の `/api-keys/current`、`/api-keys/rotate`、および `/api-keys/usage` エンドポイントです。
- **スコープ付きキー** — 特定のタスクのために作成する追加の名前付きキーで、それぞれが選択したAPIの範囲にのみ制限されます。これらは [スコープ付きキー](#scoped-keys) の下の `/api-keys` および `/api-keys/{id}` エンドポイントです。スコープ付きキーを作成してもメインキーには一切影響せず、既存のインテグレーションはそのまま使用できます。

以下のすべてのパスは、APIベースURLからの相対パスです。

```
https://api.youraiconnector.com/v1
```

すべてのリクエストは認証されている必要があります。受け入れられる4つの認証方法については、[Authentication](authentication.md)を参照してください。ここでの例では `X-API-Key` ヘッダー（およびcURL用のクエリパラメータ形式）を使用しています。

> **最初に必ずお読みください。** キーのローテーションまたは取り消しは**即時**に反映されます。呼び出しが成功した瞬間、古いキーは機能しなくなり、それを使用しているすべての統合で `401` エラーが発生し始めます。計画的に行ってください。メンテナンスウィンドウ中にローテーションを行い、すべての統合を直ちに更新してください。

---

## 現在のキーのメタデータを取得

アクティブなキーを返します。取得可能なコピーが存在する場合は `api_key` に完全なキーが、それ以外の場合はマスクされたプレビュー（最初と最後の4文字）が表示され、利用可能な場合は作成日も表示されます。`api_key` は、取得可能なコピーが保持される前に作成されたキーに対して `null` となります。一度ローテーションを行うと、新しいキーは後で再び表示できるようになります。

`GET /api-keys/current`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}
```

アカウントにAPIキーがない場合、レスポンスは `404` となり、`{ "success": false, "error": "No API key found for this account" }` が含まれます。

---

## レート制限の使用状況を取得

現在のウィンドウにおけるレート制限の使用状況を返します。これには、ウィンドウごとのリクエスト制限、これまでにカウントされたリクエスト数、残りのリクエスト数、およびウィンドウがリセットされるタイミングが含まれます。これを使用してクライアント側のスロットリングを構築し、`429` レスポンスに達する前に統合がバックオフするようにしてください。

`GET /api-keys/usage`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/api-keys/usage" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/usage", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/api-keys/usage",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}
```

現在のウィンドウでリクエストがまだ記録されていない場合、使用状況はゼロとして報告され、レスポンスにはその理由を説明する `note` フィールドが含まれます。

---

## キーをローテーション

新しいAPIキーを生成し、同時に以前のキーを無効にします。キーが漏洩した疑いがある場合や、定期的な認証情報ローテーションポリシーの一環としてこれを使用してください。

`POST /api-keys/rotate`

> **新しいキーは一度だけ表示されます。** このレスポンスで返され、その後は完全な形で取得することはできません。受け取った瞬間に安全な場所に保管してください。この呼び出しが成功した時点で以前のキーは機能しなくなるため、それを使用していたすべての統合を更新してください。

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.
```

**レスポンス**

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}
```

---

## キーの取り消し

アカウントのAPIキーを完全に削除します。取り消しは即座に行われます。Make、Zapier、カスタムスクリプトなどの統合を含む、取り消されたキーを使用する以降のすべてのリクエストは、`401`で拒否されます。その後APIアクセスを復元するには、アプリにサインインした状態でアカウント設定から新しいキーを生成してください。

`DELETE /api-keys/current`

> **元に戻すことはできません。** ローテーションとは異なり、取り消しでは代替キーは提供されません。APIアクセスを停止する意図がある場合にのみ取り消してください（例：すぐに置き換えることができないキーが漏洩した場合など）。

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys/current", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/api-keys/current",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**レスポンス**

```json
{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}
```

アカウントに取り消すべきキーがない場合、レスポンスは`404`となります。

---

## スコープ付きキー

スコープ付きキーとは、特定のタスクのために作成する追加のAPIキーであり、そのタスクに必要なアクセス権のみを保持します。典型的な例として、メッセージの送信、AIエージェントの変更、電話番号の購入などが可能なキーを渡すことなく、クライアントダッシュボード、レポートツール、または内部スクリプトを自分のアカウントに接続したい場合などが挙げられます。

制限はキー自体に付随するため、キーを保持する者は、作成時に許可された操作のみを実行できます。

**制限可能な項目**

| フィールド | 意味 |
|---|---|
| `read_only` | `true`（デフォルト）は、読み取りリクエストのみが許可されることを意味します。作成、更新、削除のリクエストはすべて拒否されます。 |
| `tags` | キーが使用できるAPIセクションのリストです。これらのドキュメントや [APIエクスプローラー](reference.md) に記載されているセクション名（`Analytics`、`Campaigns`、`Contacts`、`Messages`、`Appointments` など）を使用して記述します。リストが空の場合は、すべてのセクションが対象となります。 |
| `sub_account_ids` | キーが操作できる管理対象アカウントです。空の場合は自分自身のアカウントのみを意味し、`["*"]` は実際に管理しているすべてのアカウントを意味します。所有権はリクエストごとにチェックされます。 |
| `rate_limit_per_min` | このキーの1分あたりのリクエスト数です。独自の予算としてカウントされるため、他のインテグレーションの許容量を消費することはありません。デフォルトは `60` で、`300` を超える設定はできません。 |

キーに `expires_at` 日付（ISO 8601形式、未来の日付である必要があります）を設定することもできます。その日時を過ぎると、キーは自動的に機能しなくなります。この項目を指定しない場合、取り消されるまでキーは期限切れになりません。

> **拒否は厳格に適用されます。** リクエストがキーの許可範囲外である場合、許可されるのではなく拒否されます。読み取り専用キーで書き込みを行うと `error_code: "key_read_only"` を伴う `403` が返され、キーの許可セクション外の操作を行うと `error_code: "key_scope_denied"` を伴う `403` が返されます。スコープ付きキーで予期しない `403` が発生した場合、呼び出したエンドポイントがそのスコープに含まれていないことを意味します。キーのスコープを広げるか、メインキーを使用してください。

> **キーを管理できるのはアカウント所有者のみです。** これら4つのエンドポイントには、メインキーまたはアプリ内での所有者セッションが必要です。スコープ付きキーは、自分自身を含め、キーの一覧表示、作成、編集、取り消しを行うことはできません。そのため、制限付きキーを使用してより広範な権限を持つキーを作成することはできません。試行すると `error_code: "key_scope_denied"` を伴う `403` が返されます。同様の理由で、`API Keys` は付与可能なセクションではありません。要求すると `error_code: "invalid_scopes"` を伴う `400` が返されます。

### スコープ付きキーの一覧表示

アカウントのスコープ付きキーを新しい順（最大200件）で返します。取り消されたキーも含まれるため、何がいつ無効化されたかを確認できます。返されるのはマスクされたプレビューのみです。スコープ付きキーの値は作成時に一度だけ表示され、その後は取得できません。

`GET /api-keys`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}
```

### スコープ付きキーの作成

新しいスコープ付きキーを作成し、その値を**一度だけ**返します。

`POST /api-keys`

> **キーは一度しか表示されません。** このレスポンスにのみ含まれ、それ以降は二度と確認できません。受け取った瞬間に保存してください。紛失した場合は、取り消して別のキーを作成してください。

**ボディフィールド** — すべて任意:

| フィールド | 型 | 備考 |
|---|---|---|
| `label` | string | リストや設定に表示される、キーの独自の名称です。 |
| `scopes` | object | 上記の表にある4つのフィールドです。オブジェクト全体を省略すると、読み取り専用、`Analytics`への限定、自分のアカウントのみ、1分間に60リクエストという安全なデフォルト設定が適用されます。 |
| `expires_at` | ISO 8601 date | 任意の有効期限。未来の日付である必要があります。 |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.
```

**レスポンス** — `201 Created`

```json
{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}
```

構築時に知っておくべき詳細がいくつかあります:

- **`scopes`を省略することと、空の`tags`リストを送信することは同じではありません。** `scopes`を完全に省略すると、安全なデフォルト設定（読み取り専用、`Analytics`のみ）が適用されます。`"tags": []`を意図的に送信すると、キーはすべてのセクションを使用できるようになります。これは、制限のないキーに対する意図的なリクエストとして読み取られます。
- **`false`を明示的に送信しない限り、`read_only`は`true`のままです。** 誤字やフラグの欠落によって、書き込み可能なキーが誤って生成されることはありません。

### スコープ付きキーの更新

キーのラベル、スコープ、有効期限を変更します。3つのうち任意の組み合わせを送信してください。何も送信しない場合は`400`が返されます。

`PATCH /api-keys/{id}`

`{id}`は、リスト内のキーの`id`（`key_...`値）であり、キーそのものではありません。

> **スコープはマージされず、置き換えられます。** 送信した内容が、そのキーの完全な権限セットになります。これは意図的な仕様です。キーの権限を絞り込む際に、古い広範なアクセス権が意図せず残ってしまうことを防ぐためです。変更したいフィールドだけでなく、常に目的の完全な`scopes`オブジェクトを送信してください。

キーの値は決して変わりません。スコープ付きキーにはその場でのローテーション機能はありません。キーを更新するには、新しいキーを作成して古いキーを取り消してください。これにより、資格情報を保持している統合環境下でアクセス権が勝手に変更されることはありません。

**cURL**

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'
```

**レスポンス**

```json
{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}
```

アカウントに該当するIDのキーが存在しない場合、レスポンスは`404`となります。

### スコープ付きキーの取り消し

取り消しは即座に反映されます。そのキーを使用した次のリクエストは直ちに `401` で拒否されます。メインキーや他のすべてのスコープ付きキーには影響しません。

`DELETE /api-keys/{id}`

キーは `"revoked": true` とマークされた状態でリストに残るため、何が存在し、何にアクセスできたかの記録を保持できます。すでに取り消されたキーを取り消そうとした場合も成功しますが、何も変更されません。

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY"
```

**レスポンス**

```json
{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}
```

---

## APIキー APIエラー

APIキーのエンドポイントは、標準的なエラーエンベロープを返します：

```json
{
  "success": false,
  "error": "No API key found for this account"
}
```

APIキーのエンドポイントにおいて、キーが欠落しているか無効な場合は `401` が返され、登録されているキーがないアカウントの場合は `404` が返されます。すべてのエンドポイントで発生しうる共通のコード — `400`、`403`（ご契約プランにAPIアクセスが含まれていません）、`429`（レート制限）、および `500` — については、再試行のガイダンスとともに [エラーとページネーション](errors-and-pagination.md) に記載されています。

スコープ付きキーのエンドポイントでは、`error_code` フィールドにいくつかの名前付きコードが追加されるため、ケースを区別できます。

| `error_code` | ステータス | 詳細 |
|---|---|---|
| `key_read_only` | `403` | 読み取り専用キーで書き込みを試行しました。 |
| `key_scope_denied` | `403` | そのエンドポイントまたは管理対象アカウントではそのキーは許可されていません。あるいは、スコープ付きキーでAPIキーの管理を試行しましたが、これは許可されていません。 |
| `invalid_scopes` | `400` | 要求されたスコープに `API Keys` セクションが含まれていました。キーでキーを管理することはできません。 |
| `404` | `404` | アカウントにそのIDを持つキーが存在しません。 |

---

## 次のステップ

- [認証](authentication.md) — リクエストを認証する4つの方法と、キーのスコープがどのように適用されるかについて。
- [エラーとレート制限](errors-and-pagination.md) — ステータスコードと300リクエスト/分の制限について。