はじめに
認証
すべてのリクエストには、操作対象のXアカウントのシークレットキーを含めます。キーはアプリで作成し、読み取り専用に制限することもできます。無効にすると、その時点でキーは使えなくなります。
APIキー
- キーは
gl_live_と、それに続く32文字の英数字からなります。アプリにはgl_live_AbCdのように先頭12文字が表示されるので、どのキーかを見分けられます。 - 各キーはGemlead上のひとつのXアカウントに属し、そのアカウントのリード、ペルソナ、キャンペーン、会話にしかアクセスできません。
- キー全体が表示されるのは、作成時の一度だけです。Gemleadはキーのハッシュのみを保存するため、紛失したキーを再表示することはできません。新しいキーを作成してください。
- 1つのアカウントで有効にできるキーは20個までです。
APIはBusinessプランとEnterpriseプランで利用でき、トライアル中も使えます。アカウントのオーナーがFreeプランかStarterプランの場合、リクエストには403とコードplan_requiredが返ります。キーはそのまま残り、BusinessプランかEnterpriseプランになると再び使えるようになります。
キーの送信
キーはBearerトークンとしてAuthorizationヘッダーで送信します。Bearerトークンを設定できないツールでは、X-Api-Keyヘッダーも使えます。
キーのないリクエストには、401とコードapi_key_missingが返ります。誤ったキーではapi_key_invalid、無効にしたキーではapi_key_revokedが返ります。
# As a bearer token
curl https://gemlead.ai/api/v1/account \
-H "Authorization: Bearer $GEMLEAD_API_KEY"
# Or in X-Api-Key, for tools that cannot set a bearer token
curl https://gemlead.ai/api/v1/account \
-H "X-Api-Key: $GEMLEAD_API_KEY"スコープ
キーのスコープはreadのみ、またはreadとwriteです。writeは、データを変更するツールにだけ付与してください。
| スコープ | 許可される操作 |
|---|---|
read | すべてのGET。エクスポートは読み取りだけなので、POST /v1/exportsも含みます。 |
write | データを変更するすべてのリクエスト。POST、PATCH、PUT、DELETEです。 |
readキーでデータを変更しようとすると、403とコードinsufficient_scopeが返ります。
アカウントを取得
キーが属するXアカウントを返します。キーの動作確認として、最初に呼び出すのに適しています。
戻り値
planがbusinessまたはenterpriseのアカウントオブジェクト。
エラー
- キーが正しくありません。
- アカウントのオーナーがFreeプランかStarterプランを利用しています。
curl https://gemlead.ai/api/v1/account \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"object": "account",
"id": "a9PzK2vRtM",
"username": "acme",
"name": "Acme",
"profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg",
"plan": "business"
}キーの安全な管理
- APIはサーバーからのみ呼び出してください。ブラウザ、モバイルアプリ、公開リポジトリのコードからは呼び出さないでください。
- キーはシークレットマネージャーか、
GEMLEAD_API_KEYのような環境変数に保存してください。 - ツールごとに別のキーを発行すれば、ほかのツールに影響を与えずに1つだけ無効にできます。
- キーをローテーションするには、新しいキーを作成してデプロイし、そのあとアプリで古いキーを無効にします。
AIアシスタント
ClaudeとChatGPTは、OAuthでMCPサーバーに接続します。GemleadにログインしてXアカウントを選ぶだけで、キーをコピーする必要はありません。CursorとClaude Codeではキーも使えます。送信方法は上記と同じです。
