API へのすべてのリクエストでは、誰からのリクエストか、そしてどの組織のエンジンにアクセスできるかを示す必要があります。Lingo.dev では、そのためにすべてのリクエストへ 1 つのヘッダー X-API-Key を付けます。トークン交換も、セッションも、OAuth 対応のための面倒な実装も必要ありません。同期の localize 呼び出しでも、非同期ジョブの送信でも、付けるのは同じヘッダーです。
このシンプルさには、最初の呼び出しの前に知っておきたい注意点もあります。キーは組織スコープで、表示されるのは一度だけです。このページでは、そのヘッダーの形式、キーでアクセスできる範囲、そしてどこに保管すべきかを説明します。ヘッダーが誤っているときに API が何を返すかは、エラーとステータスコードを参照してください。
API は初めてですか？
ベース URL とエンジンの考え方は、まず 概要 で確認してください。このページは、ダッシュボードですでに API キーを取得していて、あとは送信するだけという前提で説明しています。
ヘッダー#
すべてのリクエストで、キーを X-API-Key ヘッダーに入れて送信します。
X-API-Key: your_api_key実際には、同期・非同期を問わず、どのエンドポイントでも使うヘッダーは同じです。
curl https://api.lingo.dev/jobs/localization \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"sourceLocale": "en",
"targetLocales": ["de", "ja"],
"data": { "greeting": "Welcome aboard" }
}'キーが正しければ、そのエンドポイント本来のレスポンスが返ります。この例では、202 と groupId です。ヘッダーがない、または無効な場合は 401 が返ります。このレスポンスやその他のステータスコードについては、Errors ページを参照してください。
1 つのキーでアクセスできる範囲#
キーは 1 つのエンジンではなく、組織に紐づきます。つまり、1 つのキーでその組織内のすべてのローカライゼーションエンジンにアクセスできます。エンジンごとに別の認証情報を発行する必要はありません。同じ X-API-Key でマーケティング用エンジンにもドキュメント用エンジンにもアクセスでき、組織のデフォルトを使う場合は engineId を省略できます。
この広いアクセス範囲は便利ですが、同時に慎重に扱うべきポイントでもあります。キーが漏えいすると、その組織でアクセスできるものすべてに到達されてしまいます。ほかの本番用シークレットと同じように扱ってください。環境変数やシークレットマネージャーから読み込み、決してコミットせず、必ずサーバー側で保持します。このキーはバックエンドからの呼び出しを認証するためのものであり、誰でも中身を見られるブラウザで使うものではありません。同じルールはリアルタイムの WebSocket にも当てはまります。こちらも同じキーで認証するため、接続はサーバー側で開いてください。
キーの生成と管理は、ダッシュボードの API Keys セクションから行えます。
一度保存しなければ、もう取り出せない#
キーが表示されるのは、作成した瞬間の一度だけです。ダイアログを閉じると、あとから再取得することはできません。
ページを離れる前にキーをコピーしてください
API キーは、作成時に一度だけ表示されます。表示されたらその場で、シークレットマネージャーまたは環境変数に保存してください。あとから復元することはできません。キーを紛失した場合や漏えいの疑いがある場合は、API Keys ダッシュボードで新しいキーを生成してください。
ここでは、手軽さと安全性が同じ答えを指しています。作成時にきちんとキーを保存しておくことは、もっとも手早いやり方であるだけでなく、あとから誰も確認できない認証情報のせいで本番連携が止まる事態を防ぐ唯一の方法でもあります。
次のステップ#
これで、どの呼び出しでも認証できるようになりました。次にあわせて確認したいのは、リクエストが拒否されたときに何が返るのか、そしてそのヘッダーで利用できるエンドポイントには何があるのかです。
