# 認証

すべてのAPIリクエストにはAPIキーを含める必要があります。これにより、<span data-t="appName">Your AI Connector</span>はリクエストの送信者が誰であり、どのカウントに対して操作を行うべきかを識別します。キーの送信方法は4通りあり、APIキー認証を受け付けるすべてのエンドポイントで利用可能です。ご自身の環境に最適な方法を選択してください。

APIアクセスは有料機能です。ご利用のプランに含まれていない場合、キー自体が有効であってもリクエストは`403`で拒否されます。詳細は以下の[有料機能の制限](#the-paid-feature-gate)を参照してください。キーの生成方法については[APIアクセス](../integrations/api-access.md)を参照してください。

> **HTTPSのみ。** すべてのリクエストはセキュアな接続を使用する必要があります。プレーンなHTTPリクエストは、認証が行われる前に拒否されます。

---

## 4つの方法の概要

| 方法 | 送信先 | 推奨される用途 |
|---|---|---|
| クエリパラメータ | `?apiKey=YOUR_API_KEY` | クイックテストおよびブラウザのURL |
| ヘッダー | `X-API-Key: YOUR_API_KEY` | 本番環境の統合 |
| Bearerヘッダー | `Authorization: Bearer YOUR_API_KEY` | 本番環境の統合 |
| Firebase IDトークン | `Authorization: Bearer <ID token>` | ファーストパーティアプリのセッションのみ |

複数の方法が同時に使用された場合、クエリパラメータが優先され、次に`X-API-Key`ヘッダー、その次にBearerトークンの順で優先されます。実際には、いずれか1つのみを使用してください。

---

## 1. クエリパラメータ — `?apiKey=`

Webアドレスの末尾にキーを追加します。これは最もシンプルな形式であり、常に機能するため、クイックテストやスクリプト、古いツールでの使用に最適です。

**cURL**

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

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()
```

> **注意:** Webアドレスはブラウザの履歴、サーバーのアクセスログ、プロキシログに残ります。クイックテスト以外の用途では、キーがプレーンテキストとしてディスクに書き込まれないよう、以下のヘッダーを使用する方法を推奨します。

---

## 2. `X-API-Key`ヘッダー

専用のヘッダーでキーを送信します。これによりURLにキーが含まれなくなるため、本番環境での利用が推奨されます。

**cURL**

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

**JavaScript**

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

**Python**

```python
import requests

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

---

## 3. `Authorization: Bearer` ヘッダー

キーを標準のベアラートークンとして渡すこともできます。これは、HTTPクライアントやフレームワークに `Authorization` ヘッダーのサポートが組み込まれている場合に便利です。

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()
```

APIはAPIキーとログイン用トークンを自動的に判別するため、このメソッドは `X-API-Key` とまったく同じように機能します。

---

## 4. Firebase IDトークン（ファーストパーティのみ）

<span data-t="appName">Your AI Connector</span> 独自のログインを通じてユーザーをサインインさせるファーストパーティアプリを構築している場合は、APIキーの代わりに、そのサインイン済みユーザーのFirebase IDトークンをベアラートークンとして渡すことができます。

```
Authorization: Bearer <Firebase ID token>
```

トークンはリクエストごとに検証され、サインイン済みのアカウントにマッピングされます。**このメソッドはファーストパーティのアプリセッション専用です**。外部統合からこれらのトークンを作成することはできず、通常のアプリログインを経由せずに取得する方法はありません。サーバー間通信やサードパーティ統合の場合は、APIキー（メソッド1～3）を使用してください。

---

## 使い分けについて

- **クイックテストや単発のスクリプト** → クエリパラメータ (`?apiKey=`)。入力が最も速く、ブラウザでも動作します。
- **本番環境の統合やサーバー間呼び出し** → `X-API-Key` または `Authorization: Bearer YOUR_API_KEY`。URLやログにキーが残らないようにします。
- **ログイン済みの <span data-t="appName">Your AI Connector</span> ユーザーがいるファーストパーティアプリ** → `Authorization: Bearer <Firebase ID token>`。

---

## キーのスコープ

アカウントには**メインAPIキー**が1つ存在します。これは**設定 → 統合 → APIキー**から確認できるものです。このキーは、アカウントで実行可能なすべての操作に対してフルアクセス権を持っています。

また、追加で**スコープ付きキー**を作成することもできます。これは、APIの特定の範囲のみにアクセスを許可する名前付きキーです。例えば、レポートダッシュボード用に分析機能のみに限定した読み取り専用キーなどが作成可能です。スコープ付きキーはメインキーと全く同じ方法（上記のメソッド1〜3のいずれか）で送信されますが、リクエストのたびにそのキー独自の権限がチェックされます：

- **許可されていない領域へのアクセスは拒否されます。** 読み取り専用キーで書き込みを行ったり、許可されていないセクションを呼び出したりすると、`403` が返されます。その際、`error_code` フィールドには `key_read_only` または `key_scope_denied` が含まれます。このチェックは意図的に厳格に行われます。キーの許可範囲内に明確に含まれていないものはすべて拒否されるため、これらの `403` が表示された場合は、そのキーが該当するエンドポイントをカバーしていないことを意味します。
- **独自のレート制限バジェットを持っています。** スコープ付きキーはメインキーとは別にカウントされるため、スコープ付きキーを使用するダッシュボードが混雑しても、他の統合機能が依存している許容量を使い切ることはありません。この1分あたりのバジェットは、キー作成時に選択します。
- **APIキーの管理はできません。** アカウントの所有者（サインインしている状態、またはメインキーを使用している場合）のみが、キーの一覧表示、作成、編集、ローテーション、取り消しを行うことができます。スコープ付きキーが自分自身より広範な権限を持つキーを作成することはできません。

スコープ付きキーの作成、編集、取り消しの方法については、[APIキー](api-keys.md)を参照してください。

---

## 有料機能の制限

APIアクセスは有料機能です。ご利用のプランに含まれていない場合、有効なキーを使用したリクエストであっても `403` で拒否されます。

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

If you see this, check your plan or contact [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}
```

---

## キーの安全な管理

- **キーはパスワードのように扱ってください。** メインキーはアカウントへのフルアクセス権を付与します。ツールや担当者に一部の権限のみが必要な場合は、代わりにスコープ付きキーを作成してください（[キーのスコープ](#key-scopes)を参照）。
- **サーバーサイドで管理してください。** ブラウザのJavaScript、モバイルアプリのバンドル、またはエンドユーザーが読み取れるコードには絶対に埋め込まないでください。
- **シークレットマネージャー**またはサーバーサイドの設定に保存し、ソース管理には含めないでください。
- **漏洩した場合はローテーションしてください。** ダッシュボードから新しいキーを生成するか、`POST https://api.youraiconnector.com/v1/api-keys/rotate` を呼び出すと、古いキーは即座に無効化されます。[APIキー](api-keys.md)を参照してください。
- **常にHTTPSを使用してください。** これにより、転送中のキーが暗号化されます。

---

## 次のステップ

- [はじめに](getting-started.md) — 最初のリクエストとリソースガイド。
- [エラーとページネーション](errors-and-pagination.md) — エラーの処理と結果のページング。
- [APIキー](api-keys.md) — キーのローテーション、取り消し、使用状況の確認。