APIキーは、ローカライゼーション API と MCP server へのリクエストを認証します。Lingo.dev では 2 種類のキーを用意しているので、API を呼び出すユーザーやシステムに合ったものを選んでください。
2種類のキー#
| Personal | Service | |
|---|---|---|
| 所有者 | 作成したユーザー | なし — 自動化向け |
| 認可 | 作成者の RBAC role とエンジン権限を引き継ぐ | 独自のロールおよび/またはエンジンごとのスコープを持つ |
| 所有者がアクセスを失った場合 | キーも同様にアクセスを失う | 影響なし。キー自身のロール / スコープで制御される |
| プラン | すべてのプラン | Enterprise（RBAC の利用権が必要） |
| 主な用途 | ローカル開発、MCP、アドホックスクリプト | CI/CD パイプライン、本番環境の連携 |
デフォルトは Personal キーです。Service キーは特定の個人に紐づかない組織レベルの認証情報なので、退職後も使い続けたい資格情報や、ロール変更の影響を受けたくない用途に最適です。
キーを作成する#
ダッシュボードで API Keys ページを開きます。Personal と Service は別々のタブに分かれており、Service タブは組織が Enterprise プランの場合にのみ表示されます。
Create API key をクリックし、名前（例: "Local MCP"、"Max's staging key"）を付けて、成功ダイアログに表示されるキーをコピーします。このキーは、現在の RBAC ロールとエンジンごとの権限を引き継ぎます。
キーの表示
完全な APIキーが表示されるのは作成時の一度だけです。必ずコピーして安全に保管してください — ダイアログを閉じると再取得できません。
Service キーと RBAC#
Service キーはユーザーモデルと同じ考え方です。ユーザーは、組織レベルのロール（Roles & Permissions による包括的な権限）と、特定のエンジンに追加されることで得られるエンジンごとの権限を、両方またはいずれか一方だけ持つことができます。Service キーも同様です。
- ロールのみ — ロールの権限が組織全体に適用されます。
engine:accessが含まれていれば、そのキーは組織内のすべてのエンジンにアクセスできます。 - ロールなし + エンジンスコープ — キーは作成時に選択したエンジンのみに制限されます。後からキーの横にある Engines x/y ボタンで一覧を更新できます。
- ロール + エンジンスコープ — 両方の権限は加算されます。ロールが
engine:accessを付与している場合はその包括権限が優先され、そうでない場合はエンジンごとの一覧が参照されます。 - どちらもなし — キー自体で認証はできますが、どのエンジンにもアクセスできません。スコープ設定中のプレースホルダーとしては便利ですが、本番環境では意味がありません。
権限昇格防止のガードは、作成時と編集時の両方で適用されます。
- 選択するロールは、同じ組織に属している必要があります。
- ロールの権限セットは
engine:accessの部分集合でなければなりません。より広いロール（たとえばorg:manage_teamを含むもの）は拒否されます。 - キーのスコープにエンジンを追加できるのは、自分自身がそのエンジンにすでにアクセスできる場合に限られます。
Enterprise プランが失効した場合
Service キーは RBAC の利用権に含まれます。この利用権が削除されると、組織内のすべての Service キーは 無効化 されます。リクエストは 403 を返し、エンジンスコープではなくプランに関するメッセージが表示されます。Personal キーは影響を受けません。Enterprise プランを復元するか、Personal APIキーへローテーションしてください。
キーを使う#
すべてのリクエストで、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 キーは、作成者の権限変更をリアルタイムで反映します。作成者のロールが降格されたり、エンジン権限が取り消されたりすると、次回の呼び出しからキーも同じアクセスを失います。
- 作成者が組織から削除された Personal キーは、RBAC がオフの間だけ引き続き動作します（レガシー挙動）。RBAC がオンになった時点で拒否されるため、孤立する前にローテーションしてください。
- Service キーは独自の権限を持ちます。Service タブでロールやスコープを編集すると即座に反映され、キーを削除すると失効します。
- 組織ごとのキー数に上限はありません。
