API認証
APIリクエストを認証し、各操作に必要なアクセス権を付与します。
X-API-KeyヘッダーでLingo.devのAPIキーを送信します。このセクションのAPIリファレンスでは、https://api.lingo.dev/v2をベースURLとして使用します。
GET /v2/organizations/YOUR_ORGANIZATION_ID/localization/jobs HTTP/1.1
Host: api.lingo.dev
X-API-Key: YOUR_API_KEYAPIキーからキーを作成し、サーバーの環境変数またはシークレットマネージャーに保存してください。リポジトリ、ブラウザー向けのバンドル、URL、ソースドキュメントには含めないでください。
認証情報を選ぶ #
個人キーは、そのユーザーの現在の組織への所属状況と権限に基づいて動作します。組織サービスキーは組織に属し、人の操作を介さずに稼働するサービスに適しています。アクセス権は、ロールによる権限付与とリソースへの権限付与によって決まります。明示的に付与する権限の範囲を狭くしても、ロールによってすでに付与されているアクセス権は制限されません。
APIは、ログイン済みユーザーのセッションアクセストークンもAuthorization: Bearer <access-token>として受け付けます。レビュー担当者は、自分のユーザーセッションまたは個人キーを使ってレビュー結果を送信できます。人によるレビューの判断では、判断した個人を特定する必要があるため、サービスキーでは実行できません。
リクエストごとに使用する認証方法は一つにしてください。ヘッダー名の大文字と小文字は区別されません。
組織とエンジンを選ぶ #
組織を対象とするルートでは、パスにorgIdが含まれます。ユーザーまたは個人キーに対応する組織IDを調べるには、GET /v2/users/me/membershipsを参照してください。サービスキーの場合は、そのキーを所有する組織を使用します。エンジンIDは、Studioで設定されたエンジンを識別します。アクセス可能なエンジンの一覧はGET /v2/organizations/:orgId/enginesで取得できます。
ローカライズジョブの作成、開始、読み取り、ダウンロードには、そのジョブが属する組織へのアクセス権と、使用するエンジンでの翻訳権限が必要です。プロビジョニングには、エンジンを編集または作成する権限と、要求されたガイダンスを作成する権限が必要です。翻訳のレビューには、レビュー担当者の権限とルーティングが適用されます。
組織IDやエンジンIDを渡しても、アクセス権は付与されません。呼び出し元のアクセス範囲外にあるリソースに対しては、404が返される場合があります。存在するはずのリソースが見つからない場合は、IDと呼び出し元の権限の両方を確認してください。
アクセス失敗の原因を調べる #
HTTPステータスだけでなく、問題レスポンスも確認してください。401は、認証情報がないか、無効または期限切れであることを示します。402は、課金またはプランに関する状態を示します。ロールベースのアクセス制御のダウングレード後にサービスキーが無効になった場合も含まれます。403は、権限が拒否されたか、ユーザー個人を識別する必要があることを示します。エンジン設定やアカウントの制限については、それぞれに応じた修正が必要です。
原因を調べられるように、問題のtype、ステータス、機密情報ではないリソースIDを保存してください。認証ヘッダーは絶対にログに記録しないでください。
キーをローテーションする #
新しいキーを作成し、必要なアクセス権を付与して、サービスのシークレットを更新します。古いキーを失効させる前に、新しいキーで既存のジョブを取得し、結果をダウンロードできることを確認してください。記録済みのジョブIDはそのまま保管してください。認証情報をローテーションしても、ジョブIDは変わりません。