はじめに

認証

すべてのリクエストを Lovely Router の API キーで認証します。キーは、お使いの SDK が普段送っているヘッダーでそのまま送れます。

残高を使うリクエストには、すべて API キーが必要です。1 つのキーで API 全体を利用できます。Claude・GPT・Gemini の各モデル、データツール、ブラウザエージェント、MCP サーバーのすべてが対象です。

API キーを取得する#

ダッシュボードの API キーでキーを作成します。キーは lr- に続く 40 文字の英数字です。表示されるのは作成時の一度だけです。Lovely Router はキーのハッシュしか保存しないため、紛失したキーは復元できません。そのキーを失効させ、新しいキーを作成してください。

キーは環境変数に保存します。このドキュメントの例はすべて $LOVELY_API_KEY からキーを読み込みます。

Shell

export LOVELY_API_KEY="lr-..."

キーで使える金額や呼び出せる対象を制限するには、API キーを参照してください。

キーを送る#

Lovely Router は、各ベンダーの API がキーを受け取るどの場所でもキーを受け付けます。4 つの方法はすべてのエンドポイントで使えるため、SDK やツールが既定で送る方法のままで構いません。

送り方	例	使用している SDK・ツール
`Authorization` ヘッダー	`Authorization: Bearer lr-...`	OpenAI SDK、Claude Code（`ANTHROPIC_AUTH_TOKEN`）、データツール、ブラウザエージェント、MCP クライアント
`x-api-key` ヘッダー	`x-api-key: lr-...`	Anthropic SDK
`x-goog-api-key` ヘッダー	`x-goog-api-key: lr-...`	Google Gen AI SDK、Gemini CLI
`key` クエリパラメータ	`?key=lr-...`	Gemini の REST の例

1 つのリクエストに複数含まれている場合は、Authorization: Bearer、x-api-key、x-goog-api-key、?key= の順で最初に見つかったものが使われます。

ヘッダーを優先する

クエリ文字列に入れたキーは、プロキシのログ、シェルの履歴、ブラウザの履歴に残ります。?key= はヘッダーを送れないツールに限って使ってください。

キーが使えるか確認する#

トークンのカウントには有効なキーが必要ですが、料金はかかりません。そのため手軽な確認方法として使えます。200 が返れば、キーが有効で、そのモデルの使用が許可されています。

Shell

curl https://lovelyrouter.com/v1/messages/count_tokens \
  -H "x-api-key: $LOVELY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "messages": [{"role": "user", "content": "ping"}]
  }'

キーが不要なエンドポイント#

カタログ系のエンドポイントは公開されているため、登録前でもモデルやツールを閲覧できます。これらに送られたキーは無視されます。ただしプランナーは例外で、キーがあればより高い上限が適用されます。

エンドポイント	返す内容
`GET /v1/models`	利用可能なすべてのモデルと、そのコンテキストサイズ、価格、チャネルグループ
`GET /v1beta/models`	同じ一覧の Gemini 形式
`GET /v1/tools`	データツールのカタログ
`GET /v1/tools/{id}`	1 つのツールの入力スキーマ、入力例、価格
`POST /v1/tools/discover`	キーワード検索に一致するツール
`POST /v1/tools/suggest`	タスクを実行するための、手順ごとのツールプラン。キーなしの場合、匿名の呼び出し元全体で 1 分あたり 100 リクエストを共有します。キーありの場合は、そのキーに対して 1 分あたり 100 リクエストが割り当てられます。

それ以外はすべてキーが必要です。モデルへのリクエスト（トークンのカウントを含む）、ツールの実行、すべての /v1/browser エンドポイント、MCP 経由のツール実行が該当します。

認証エラー#

キーがない、不明、失効済み、または有効期限切れの場合は 401 が返ります。レスポンス本文は、呼び出した API の形式に従います。

原因	メッセージ
モデルへのリクエストにキーがない	`Missing API key`
キーが不明または失効済み、もしくはアカウントが停止されている	`Invalid or revoked API key`
キーが有効期限を過ぎている	`This API key has expired`
`/v1/tools` または `/v1/browser` で、キーがない、または不明・失効済みのキーを使っている	`Missing, invalid or revoked API key`

JSON

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid or revoked API key"}}

有効なキーでも、許可された範囲を超える操作は拒否されます。許可リストにないモデルには 403、利用上限に達したときは 402、レート制限に達したときは 429 が返ります。上限に達したときの動作とエラーを参照してください。

キーを安全に保つ#

キーはサーバー側に置く。 Web ページ、モバイルアプリなど、ユーザーに配布するものにキーを含めないでください。API はあらゆるオリジンからのリクエストを受け付けるため、フロントエンドのコードに含まれたキーは、それを開いた誰にでもコピーされ、使われてしまいます。
キーは環境変数やシークレットマネージャーから読み込む。 コミットしないでください。.env ファイルは .gitignore に追加します。
アプリと環境ごとに別々のキーを使う。 そうすればステージング用のキーが漏れても本番環境には影響せず、ログでどのキーが各リクエストを送ったかも分かります。
各キーでできることに上限を設ける。 エージェント、CI ジョブ、他の人が使うキーには、利用上限、モデルの許可リスト、有効期限を設定してください。API キーを参照してください。
キーは定期的にローテーションする。 アクセス権を持つ人が離れたときは、すぐにローテーションしてください。キーをローテーションするを参照してください。

キーが漏洩した場合

すぐに API キーで失効させてください。失効は次のリクエストから適用されます。その後、代わりのキーを作成し、ログに見覚えのないトラフィックがないか確認します。