認証 #

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

APIアクセスは有料機能です。ご利用のプランに含まれていない場合、キー自体が有効であってもリクエストは403で拒否されます。詳細は以下の有料機能の制限を参照してください。キーの生成方法についてはAPIアクセスを参照してください。

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

4つの方法の概要 #

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

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

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

cURL

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

JavaScript

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

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

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

JavaScript

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

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

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

JavaScript

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

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トークン（ファーストパーティのみ） #

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

Authorization: Bearer <Firebase ID token>

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

使い分けについて #

• クイックテストや単発のスクリプト → クエリパラメータ (?apiKey=)。入力が最も速く、ブラウザでも動作します。
• 本番環境の統合やサーバー間呼び出し → X-API-Key または Authorization: Bearer YOUR_API_KEY。URLやログにキーが残らないようにします。
• ログイン済みの Your AI Connector ユーザーがいるファーストパーティアプリ → 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アクセスは有料機能です。ご利用のプランに含まれていない場合、有効なキーを使用したリクエストであっても 403 で拒否されます。

{
  "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 hi@youraiconnector.com. A missing or wrong key returns 401 instead:

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

キーの安全な管理 #

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

次のステップ #

• はじめに — 最初のリクエストとリソースガイド。
• エラーとページネーション — エラーの処理と結果のページング。
• APIキー — キーのローテーション、取り消し、使用状況の確認。