OAuth クライアントの作成方法

API バージョン 2026-10-affable-towhee

「連携」ページで「クライアントを作成」を押す前に、3つのことを決めてください。クライアントに何を許可するか、どのプロセスがそのシークレットを保持するか、そしてその呼び出しの費用を誰が負担するかです。ルールは認証ガイドに記載されています。このページでは、それを架空の2社、Luba と Farducks に当てはめます。

Luba: Dive Deck

Luba は自律航行する潜水艇で輸送・ライドシェアサービスを運営しています。Dive Deck は、キャビンの画面で各乗客にその潜航のフレーズを、乗客が学習中の言語で表示します。Luba の運用チームは、利用枠があとどれだけ残っているかを監視しています。

Luba は Luba Dive Deck というクライアントを1つ作成し、「語彙を生成」(vocab:generate)と「使用状況を読み取る」(usage:read)を許可して、課金を「プランの利用枠」(allowance)にします。このクライアントは2つのプロセスで共有し、それぞれが交換時に必要なスコープだけを要求します。scope を省略した交換は、クライアントに許可されたすべてのスコープを取得します。クライアントに許可されていないスコープを要求した交換は invalid_scope で全体が拒否され、黙って範囲が狭められることはありません。

配車サーバーは各潜航のフレーズを作成します。要求するのは vocab:generate だけなので、そこからトークンが漏れても Luba の使用状況は読み取れません。

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

運用ダッシュボードは、同じクライアント ID とシークレットを使う、サーバー側の2つ目のプロセスです。要求するのは usage:read だけで、利用枠の残りを読み取ります。

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

どちらのプロセスも Luba のサーバー上で動きます。キャビンのタブレットは配車サーバーにフレーズを要求するだけで、シークレットもトークンも保持しません。乗客が触れられるデバイス上にあるものは、何であれ読み取られる可能性があるからです。その理由は認証ガイドの「シークレットとトークンはサーバー上に置く」で説明しています。

同じクライアントを、クローンして実行できるプロジェクトとして： integrations/luba-dive-deck

Farducks: Batter Rewards

Farducks はフィッシュアンドチップスのコンビニエンスストアチェーンです。注文を揚げている間に、ロイヤルティアプリ Batter Rewards が Farducks 自身のバックエンドに短いレッスンプランを要求し、それを読み戻します。アプリもレジも呼び出すのは Lingara ではなく Farducks のバックエンドなので、どちらもシークレットを保持しません。

Farducks は Farducks Batter Rewards というクライアントを1つ作成し、「レッスンプランを作成」(lesson_plans:write)と「レッスンプランを読み取る」(lesson_plans:read)を許可して、課金を「プランの利用枠」(allowance)にします。現在クライアントを作成できる課金方法はこれだけで、クライアントの課金方法は作成時に固定されます。もう1つの方式である metered(「従量課金」)については、認証ガイドの「呼び出しの費用は誰が負担するか」で説明しています。

バックエンドは lesson_plans:write だけを要求してプランを作成します。レスポンスはストリーミングされ、その started イベントにプランの plan_id が含まれます。

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/lesson-plans" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context":"Ordering food at a night market","source_lang":"en","target_lang":"zh","level":2}'

ID にその plan_id を設定し、lesson_plans:read を要求してプランを読み戻します。1回の交換で、クライアントのスコープを scope にスペース区切りで複数要求することもできます。ここでの各コマンドが1つだけを要求するのは、それぞれが1回の呼び出しから組み立てられているためです。

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/lesson-plans/$ID" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

ある日、シークレットがサポートチケットに貼り付けられてしまいます。Farducks は「連携」ページで「新しいシークレット」を押してバックエンドにデプロイし、古いシークレットの「最終使用」の日付が変わらなくなるまで待ってから、古いシークレットの「取り消す」を押します。その時点から、古いシークレットと交換されたすべてのアクセストークンが拒否されます。シークレットは2つまでという上限と、クライアントの唯一のシークレットを取り消せない理由は、認証ガイドの「シークレットをローテーションする」に記載されています。

同じクライアントを、クローンして実行できるプロジェクトとして： integrations/farducks-batter-rewards

次に読むもの

認証ガイドでは、交換のエラー、トークンの有効期限が切れたときの対処、ローテーションのルールを扱います。バージョンガイドでは、クライアントが固定されるバージョンと、1回の呼び出しだけ別のバージョンを選ぶ方法を扱います。

翻訳と英語版リファレンスの内容が異なる場合は、英語版リファレンスが正しいものとします。