APIキー
APIキーは、ローカライゼーション API と MCP server へのリクエストを認証します。Lingo.dev では 2 種類のキーを用意しているので、API を呼び出すユーザーやシステムに合ったものを選んでください。
2種類のキー#
| Personal | 組織 | |
|---|---|---|
| 所有者 | 作成したユーザー | なし — 自動化向け |
| 認可 | 作成者の RBAC role とエンジン権限を引き継ぐ | RBAC なし:組織全体の読み取り・翻訳アクセス権。RBAC あり:キー固有のロール、エンジンごとのスコープ、またはその両方 |
| 所有者がアクセスを失った場合 | キーも同様にアクセスを失う | 影響なし。組織に属するため |
| プラン | すべてのプラン | すべてのプランで利用可能。カスタムロールと制限の設定には Enterprise の RBAC が必要 |
| 主な用途 | ローカル開発、MCP、アドホックスクリプト | CI/CD パイプライン、本番環境の連携 |
デフォルトは個人用キーです。組織キーは、特定の個人に紐づかない組織レベルの認証情報です。従業員の退職後も使い続けられ、ロール変更の影響も受けない認証情報が必要な場合に適しています。
キーを作成する#
設定で API キーページを開きます。個人キーと組織キーは、それぞれ別のタブに表示されます。どちらもすべてのプランで利用できます。組織キーの作成には、API キーの管理権限(org:manage_api_keys)が必要です。
New personal key をクリックし、名前(例: "Local MCP"、"Max's staging key")を付けて、表示されたキーをコピーします。このキーには、現在の RBAC ロールとエンジンごとの権限付与が引き継がれます。
キーの表示
完全な APIキーが表示されるのは作成時の一度だけです。必ずコピーして安全に保管してください — ダイアログを閉じると再取得できません。
組織キーと RBAC#
RBAC がない場合、通常の組織キーには組織全体の読み取り・翻訳アクセス権が適用されます。Enterprise の RBAC では、次のように権限を絞って設定できます。
- ロールのみ:ロールの権限が組織全体に適用されます。指定できる権限は
engine:readとengine:translateのみです。 - ロールなし+エンジンスコープ:キーに指定されたエンジンにアクセスできます。
- ロール+エンジンスコープ:両方で付与されたアクセス権が適用されます。スコープを設定しても、ロールが持つ、より広範な権限は制限されません。
- どちらもなし:RBAC が有効な間、キーはどのエンジンにもアクセスできません。
組織キーの作成には、API キーの管理権限が必要です。ロールの割り当てや変更、エンジンへのアクセス権の付与、コンテンツスコープの設定には、RBAC も必要です。ロールはその組織に属している必要があります。また、アクセス権を付与できるのは、自分が翻訳に使用できるエンジンのみです。コンテンツスコープには、自分が編集できる用語集、ブランドボイス、ルールセットを指定できます。
RBAC を削除する前に
RBAC を削除すると、通常の組織キーは組織全体の読み取り・翻訳アクセス権に戻ります。保存済みのロールやエンジンの制限は、アクセスを制限しなくなります。これらの制限が必要な場合は、RBAC を削除する前にキーを失効させるか、新しいキーに切り替えてください。この説明は通常のサービスキーを対象としています。SCIM キーなど、特定の用途向けの認証情報には、別のアクセス要件があります。
キーを使う#
すべてのリクエストで、APIキーを X-API-Key ヘッダーに渡します。どちらの種類でもワイヤーフォーマットは同じです。
curl -X POST https://api.lingo.dev/process/localize \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"engineId": "eng_abc123", "sourceLocale": "en", "targetLocale": "de", "data": {"greeting": "Hello"}}'同じキーを localization API と MCP server の両方で使えます。
セキュリティ#
- キーはハッシュとして保存されるため、Lingo.dev でも作成後にキーを再取得することはできません。ローテーションする場合は、削除して再作成してください。
- Personal キーは、作成者の権限変更をリアルタイムで反映します。作成者のロールが降格されたり、エンジン権限が取り消されたりすると、次回の呼び出しからキーも同じアクセスを失います。
- 個人キーを使うには、作成者が組織のメンバーであり続ける必要があります。同僚の退職後も自動化を継続する必要がある場合は、組織キーを使用してください。
- 組織キーは独自の権限を持ちます。ロールやスコープの変更は即時に反映され、キーを削除すると失効します。
- 組織ごとのキー数に上限はありません。