APIキー

APIキーは、ローカライゼーション API と MCP server へのリクエストを認証します。Lingo.dev では 2 種類のキーを用意しているので、API を呼び出すユーザーやシステムに合ったものを選んでください。

2種類のキー#

デフォルトは個人用キーです。組織キーは、特定の個人に紐づかない組織レベルの認証情報です。従業員の退職後も使い続けられ、ロール変更の影響も受けない認証情報が必要な場合に適しています。

キーを作成する#

Settings の API keys ページを開きます。個人用キーと組織キーは別々のタブに分かれており、Organization タブは Enterprise プランで利用できます。

組織キーと RBAC#

組織キーはユーザーモデルと同じ考え方です。ユーザーは、組織レベルのロール（Roles & Permissions による包括的な権限）と、特定のエンジンに追加されることで得られるエンジンごとの権限付与の、両方またはいずれかを持てます。組織キーも同様です。

• ロールのみ — ロールの権限が組織全体に適用されます。engine:access が含まれていれば、そのキーは組織内のすべてのエンジンにアクセスできます。
• No role + engine scope — キーは作成時にチェックしたエンジンのみに制限されます。エンジン一覧は、後からキーを編集して更新できます。
• ロール + エンジンスコープ — 両方の権限は加算されます。ロールが engine:access を付与している場合はその包括権限が優先され、そうでない場合はエンジンごとの一覧が参照されます。
• どちらもなし — キー自体で認証はできますが、どのエンジンにもアクセスできません。スコープ設定中のプレースホルダーとしては便利ですが、本番環境では意味がありません。

権限昇格防止のガードは、作成時と編集時の両方で適用されます。

• 選択するロールは、同じ組織に属している必要があります。
• ロールの権限セットは engine:access の部分集合でなければなりません。より広いロール（たとえば org:manage_team を含むもの）は拒否されます。
• キーのスコープにエンジンを追加できるのは、自分自身がそのエンジンにすでにアクセスできる場合に限られます。

キーを使う#

すべてのリクエストで、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 がオンになった時点で拒否されるため、孤立する前にローテーションしてください。
• 組織キーは独自の権限を持ちます。ロールやスコープの変更は即時に反映され、キーを削除すると失効します。
• 組織ごとのキー数に上限はありません。

次のステップ#