2026.10.18 AWS

API GatewayのAPIキー：使用量プランでスロットリングとクォータを設定する手順と認可に使わない理由

Q: APIキーをヘッダーではなくクエリ文字列で受け取れますか？

API Gatewayが標準で読む場所は X-API-Key ヘッダーか、Lambdaオーソライザーの usageIdentifierKey の2つで、クエリ文字列は選択肢にありません。クエリで送る既存クライアントを残したい場合は、キーソースを AUTHORIZER にし、オーソライザーでクエリの値を読み取って返す方法になります。ただしクエリ文字列はアクセスログやブラウザ履歴に残りやすいため、新規の設計では避けてください。

Q: クォータを超えたらどんなレスポンスが返り、いつ回復しますか？

クォータ超過のゲートウェイレスポンスは QUOTA_EXCEEDED で、ステータスコードは429です。毎秒のスロットリングに当たったときも429ですが、こちらは THROTTLED で、トークンが補充されれば数秒以内に通る状態へ戻ります。クォータは period に指定した日・週・月の区切りで回復し、それまでに増枠が必要なときの手段は、 update-usage による今期の残数の書き換えです。両者の本文はゲートウェイレスポンスで別々に変えられます。

API GatewayのAPIキー：使用量プランでスロットリングとクォータを設定する手順と認可に使わない理由

Amazon API GatewayのAPIキーは、単体では何も制限しません。使用量プランに結び付け、メソッドで「APIキー必須」を有効にして初めて、キーごとのスロットリング（毎秒の上限）とクォータ（日・週・月の総量）が有効になる仕組みです。本記事では、CLIでキーを発行してx-api-keyヘッダーで呼び出し、get-usageで使用量を確かめるまでの手順を示したうえで、AWS自身が「APIキーを認証や認可に使わないで」と明記している理由と、Lambdaオーソライザーと組み合わせる構成を解説します。API Gateway全体の役割はAPIゲートウェイの役割と導入判断で整理しています。

まとめ：APIキーは呼び出し量の計測と制限に使い、認可はIAMやCognitoに任せる

APIキーと使用量プランが向いているのは、取引先ごとに「毎秒10件・月10万件まで」のような呼び出し枠を契約に載せて外部公開するREST APIです。キーで呼び出し元を識別し、プランで枠を決め、get-usageで日別の消費量を取り出せます。HTTP APIにはこの機能がありません。

一方で、APIキーを「この相手だけが呼べる」という認可の手段にしてはいけません。同じ使用量プランに複数のAPIが入っていれば、1つのAPI用に渡したキーで残りのAPIも呼べます。キーはヘッダーで送られるため、ログやプロキシに残ります。誰が呼べるかの判定はIAM、Cognito、Lambdaオーソライザーで行い、APIキーはその後段で「どの枠を消費するか」を決める役に限定してください。クォータもベストエフォートで、超過を完全には止めないため、費用の上限はAWS Budgetsで別に監視します。

API GatewayのAPIキーと使用量プランの仕組みとREST API限定の制約

設定を始める前に、キー・プラン・ステージの3者の関係と、制限がどの順で掛かるかを押さえます。ここを曖昧にしたまま設定すると、「キーを作ったのに制限が効かない」状態になります。

APIキー・使用量プラン・ステージの関係と1ステージ1プランの制約

使用量プランとAPIキーの公式解説によると、使用量プランは「どのAPIステージを、どのくらいの頻度で呼べるか」を定義し、APIキーはそのプランに属する呼び出し元を識別します。キーの値は20〜128文字の英数字で、名前は1,024文字までです。

関係は多対多ですが、1つ制約があります。1つのAPIキーは複数のプランに入れられ、1つのプランは複数のステージを持てるものの、同じステージについてキーが属せるプランは1つだけです。もう1つ見落としやすいのが合算の単位です。スロットリングとクォータはキーごとに、プラン内の全ステージを合算して数えられます。prodとstgを同じプランに入れると、検証環境の呼び出しが本番の月間枠を食います。

スロットリングの4階層と適用順、アカウント上限1万RPSとの関係

リクエストスロットリングの公式解説では、API Gatewayはトークンバケット方式で制限し、設定は4種類あって次の順に適用されると説明されています。

使用量プランで決めた、キー（クライアント）単位またはメソッド単位の上限
ステージ設定で決めた、メソッド単位の上限
アカウント単位・リージョン単位の上限
AWSがリージョン全体に掛ける上限（利用者は変更不可）

プランの「レート」はバケツへトークンを足す毎秒の速度、「バースト」はバケツの容量です。どの層で止まっても、呼び出し元には429 Too Many Requestsが返ります。API Gatewayのクォータ一覧では、アカウント単位の上限はREST・HTTP・WebSocketの全APIを合わせて10,000RPS、バーストは5,000件です（2026年10月時点・東京リージョンを含む多くのリージョン）。プランのキー単位の値はこの上限を超えて設定しても意味がありません。1社の取引先が枠いっぱいまで呼ぶと、同じアカウントの他のAPIが429を受けることもあります。トークンバケットの考え方そのものはAPIレート制限の5方式と429設計で比較しています。

HTTP APIではAPIキーも使用量プランも使えないという選定時の分岐

REST APIとHTTP APIの選び方の公式ページは、APIキーとクライアント単位のレート制限が必要ならREST APIを選ぶよう案内しています。HTTP APIにはステージ単位のスロットリングしかなく、取引先ごとに枠を分けられません。

REST APIはHTTP APIより単価が高いため、APIキーのためだけに型を選ぶと費用が変わります。月間の呼び出し数ごとの差額はAPI Gatewayの料金の実額計算で確かめてから決めてください。

APIキーと使用量プランをCLIで作成し、x-api-keyで呼び出すまでの手順

ここからは東京リージョンの既存REST API（ID abcde12345、ステージ prod）に、取引先A社用のキーと枠を設定します。コマンドはAWS CLI v2で、bashを前提にしています。

create-api-keyでキーを発行し、値を取り出すときの注意点

キーの値はAPI Gatewayの自動生成に任せるのが原則です。公式のベストプラクティスにも、自分で値を決めずに生成させるよう書かれています。作成後に値は変えられないため、漏えい時は新しいキーを作って差し替えることになります。

# キーを作成し、IDだけを変数に受ける
KEY_ID=$(aws apigateway create-api-key --region ap-northeast-1 \
  --name partner-a --description "A社 本番" --enabled \
  --query id --output text)

# 値は --include-value を付けたときだけ返る。取引先への受け渡しにだけ使う
aws apigateway get-api-key --region ap-northeast-1 \
  --api-key "$KEY_ID" --include-value --query value --output text

以後の運用ではキーの値ではなくIDで扱います。値を受け渡す経路と保管、定期的な差し替えの設計はAPIキー管理の発行・保管・失効の実装で扱っています。

create-usage-planでレート・バースト・月間クォータを設定する

使用量プランを作り、ステージを結び付け、キーを追加します。次の例は毎秒10件・バースト20件、月10万件の枠です。

PLAN_ID=$(aws apigateway create-usage-plan --region ap-northeast-1 \
  --name partner-a-standard \
  --api-stages apiId=abcde12345,stage=prod \
  --throttle rateLimit=10,burstLimit=20 \
  --quota limit=100000,offset=0,period=MONTH \
  --query id --output text)

aws apigateway create-usage-plan-key --region ap-northeast-1 \
  --usage-plan-id "$PLAN_ID" --key-type API_KEY --key-id "$KEY_ID"

QuotaSettingsのAPIリファレンスどおり、periodに指定できるのはDAY・WEEK・MONTHの3つです。rateLimitは小数を受け付けるので、0.5なら2秒に1件の割合になります。キーをプランに追加してから実際に効くまで数分かかることがある、と公式に注記されています。追加直後の試験で403が返っても、すぐに設定を疑わず数分待ってください。

メソッドのAPIキー必須化と再デプロイを忘れると制限が効かない理由

プランとキーを作っただけでは、APIはキー無しでも呼べます。APIキー設定の公式手順によると、メソッドのapiKeyRequiredをtrueにし、ステージへ再デプロイして初めて要求が有効になります。

aws apigateway update-method --region ap-northeast-1 \
  --rest-api-id abcde12345 --resource-id a1b2c3 --http-method GET \
  --patch-operations op=replace,path=/apiKeyRequired,value=true

aws apigateway create-deployment --region ap-northeast-1 \
  --rest-api-id abcde12345 --stage-name prod \
  --description "require api key"

必須化はメソッドごとの設定です。リソースを追加したときに新しいメソッドだけ必須化を忘れると、そこはキー無しで呼べ、プランの枠も数えられません。デプロイ前にget-resourcesの結果からapiKeyRequiredがfalseのメソッドを一覧にし、意図した公開メソッド以外が混じっていないかを確かめる手順を入れておくと漏れを防げます。

curlでx-api-keyを付けて200・403・429を確かめる検証手順

キーの値を環境変数に入れ、ヘッダーあり・なし・連打の3通りで呼びます。

URL=https://abcde12345.execute-api.ap-northeast-1.amazonaws.com/prod/orders

# キーあり: 200
curl -s -o /dev/null -w "%{http_code}\n" -H "x-api-key: $API_KEY" "$URL"

# キーなし、または誤ったキー: 403
curl -s -o /dev/null -w "%{http_code}\n" "$URL"

# 50件を並列に送り、バースト20を超えた分が429になるかを見る
seq 50 | xargs -P 50 -I{} curl -s -o /dev/null -w "%{http_code}\n" \
  -H "x-api-key: $API_KEY" "$URL" | sort | uniq -c

ゲートウェイレスポンスの種類一覧では、キー不正はINVALID_API_KEY（403）、クォータ超過はQUOTA_EXCEEDED（429）、スロットリングはTHROTTLED（429）と分かれています。同じ429でも原因が違うので、利用者向けの本文はゲートウェイレスポンスで書き分けると問い合わせが減ります。スロットリングとトークンバケットは目標値で、並列の試験では20件ちょうどで切れるとは限りません。

使用量の確認とクォータ調整、取引先ごとの契約に応じたプラン設計の実務

キーを配った後の運用は、消費量の確認、一時的な枠の追加、プランの設計変更の3つに集約されます。

get-usageで日別の使用量と残りクォータをキー単位で取り出す

get-usageのCLIリファレンスによると、結果はキーごとに日別の[使用数, 残数]の配列で返ります。

aws apigateway get-usage --region ap-northeast-1 \
  --usage-plan-id "$PLAN_ID" --key-id "$KEY_ID" \
  --start-date 2026-10-01 --end-date 2026-10-18 \
  --query "items" --output json

月末に枠を使い切りそうな取引先には、update-usageのCLIリファレンスの例のとおり、--patch-operations op=replace,path=/remaining,value=5000で今期の残数だけを一時的に書き換えられます。プラン本体の設定は変わらないため、翌期に適用されるのは元の枠です。リクエスト単位の記録が要るなら、アクセスログに$context.identity.apiKeyIdを入れます。同じ一覧にある$context.identity.apiKeyはキーの値そのものを出すため、ログに残すのは避けてください。ログの出力設定はAPI Gatewayのログ設定の手順を参照してください。

取引先の契約ごとに使用量プランを分ける設計と上限300・10の制約

プランは「取引先ごと」ではなく「契約の段階ごと」に作るのが基本です。ライト・スタンダード・エンタープライズのようにプランを3〜5個用意し、取引先のキーをどれかに入れます。REST APIのクォータ表の上限は次のとおりです（2026年10月時点）。

項目	既定の上限	引き上げ
APIキー（アカウント・リージョンあたり）	10,000	不可
使用量プラン（アカウント・リージョンあたり）	300	可
1つのAPIキーが属せる使用量プラン	10	可
プラン内1ステージのメソッド別スロットリング設定	20	可

取引先ごとに専用プランを作ると300で行き詰まります。同じ表の改善策でも、1つのキーは1つのプランにだけ入れ、プラン側に複数のAPIを結び付ける形が推奨されています。キーの1万件は引き上げできないため、エンドユーザー1人に1キーを配る設計は、利用者数が数千を超える見込みなら採用しないでください。プランの更新API（UpdateUsagePlan）には、アカウント全体で20秒に1回という呼び出し制限もあります。契約変更のたびにプラン本体を書き換える自動化はこの制限に当たりやすいため、プランは固定し、キーの所属を付け替える形にします。

メソッド単位のスロットリングで重い集計系APIだけを絞る設定例

全体は毎秒10件で構わないが、重い集計APIだけは毎秒1件に抑えたい、という場合はプランにメソッド単位の上限を足します。使用量プランの保守の公式手順にある、ステージのthrottleをJSONのマップで置き換える形が書き間違えにくい方法です。

# /reports の GET だけ毎秒1件・バースト2件にする
# throttle を丸ごと置き換えるため、既存のメソッド単位設定も同じマップに並べて渡す
aws apigateway update-usage-plan --region ap-northeast-1 \
  --usage-plan-id "$PLAN_ID" \
  --patch-operations op=replace,path=/apiStages/abcde12345:prod/throttle,value='{"/reports/GET":{"rateLimit":1.0,"burstLimit":2}}'

# 反映後の設定を確かめる
aws apigateway get-usage-plan --region ap-northeast-1 \
  --usage-plan-id "$PLAN_ID" --query "apiStages[].throttle"

マップのキーは「リソースパス/メソッド」の形です。1ステージあたりの設定は20個までなので、細かく刻むより「重い数本だけ」に絞ります。キーと無関係に全利用者のメソッドを抑えたいなら、プランではなくステージのメソッド設定で掛けるほうが管理しやすくなります。

APIキーを認可に使ってはいけない理由と、オーソライザーとの組み合わせ方

APIキーを入れた時点で「認証付きのAPIになった」と扱われる例が少なくありません。公式の注意書きと、代わりの構成を確認します。

同じプランの別APIまで呼べてしまう公式の警告とヘッダー漏えいの経路

使用量プランの公式ページのベストプラクティスは、最初の項目で「APIキーをAPIへのアクセス制御のための認証や認可に使わない」と述べ、理由として、1つの使用量プランに複数のAPIがある場合、そのうち1つのAPI用の有効なキーを持つ利用者がプラン内の全APIを呼べる点を挙げています。キーには機密情報を含めないこと、キーはログに残りうるヘッダーで送られることも併記されています。

実際の漏えい経路は、取引先のフロントエンドのJavaScriptにキーを埋め込む、モバイルアプリに同梱する、サポート問い合わせにcurlの行を貼る、の3つが典型です。APIキーにはスコープも有効期限も無く、漏れた後に分かるのは「誰の枠が消費されたか」だけです。認可の方式の選び方はAPI認証の設計と方式選定マトリクスで整理しています。

LambdaオーソライザーのusageIdentifierKeyでキー配布をやめる構成

認可と使用量計測を両立させるなら、APIキーを利用者に配らない構成が取れます。APIキーソースの公式解説によると、キーの読み取り元はHEADER（X-API-Keyヘッダー）とAUTHORIZERの2つです。AUTHORIZERにすると、Lambdaオーソライザーの出力に含めたusageIdentifierKeyがキーとして扱われます。

import os

# 取引先ID → 使用量プランに登録済みのAPIキー値（実運用ではSecrets Manager等から読む）
TENANT_KEYS = {"partner-a": os.environ["PARTNER_A_KEY"]}

def lambda_handler(event, context):
    # JWTの署名・有効期限・発行者を検証して取引先IDを得る（verify_jwtは自前実装かライブラリ）
    claims = verify_jwt(event["authorizationToken"])
    return {
        "principalId": claims["sub"],
        "policyDocument": {
            "Version": "2012-10-17",
            "Statement": [{"Action": "execute-api:Invoke", "Effect": "Allow", "Resource": event["methodArn"]}],
        },
        "usageIdentifierKey": TENANT_KEYS[claims["tenant_id"]],
    }

APIのキーソースはaws apigateway update-rest-api --rest-api-id abcde12345 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZERで切り替え、再デプロイします。利用者が持つのは有効期限付きのトークンだけで、キーの値は社内に留まる構成です。取引先の追加はプランへのキー登録と対応表の更新で済みます。

クォータはベストエフォートでコスト上限にならないため予算は別で守る

公式ページは、使用量プランのスロットリングとクォータは厳密な上限ではなくベストエフォートで適用され、利用者が設定値を超える場合があると明記しています。そのうえで、コストの監視にはAWS Budgets、リクエストの管理にはAWS WAFを検討するよう案内しています。

月10万件のクォータを「月の請求の上限」と読み替えて契約書に書くのは避けてください。悪意ある大量送信への備えは、入口で落とすAWS WAFのレートベースルールの役割です。取引先の拠点が固定ならAPI GatewayのIP制限も重ねられます。

API GatewayのAPIキーと使用量プランを採用する条件と見送る場面

ここまでの仕様から、どの条件で使い、どの条件で使わないかを言い切ります。

外部公開APIで取引先別の呼び出し上限を契約に載せるなら採用する

取引先数社〜数百社にREST APIを公開し、契約の段階ごとに毎秒・月間の枠を決めて請求や増枠交渉の根拠にしたい。この条件なら使用量プランを採用します。自前でRedisのカウンターを組むより、get-usageで日別の消費量が取れる分だけ運用が軽くなります。ただし前の章のとおり、認可はオーソライザーで別に行うことが前提です。取引先向けAPIの公開範囲や認可方式、契約枠の設計まで含めて検討する場合は、API開発・システム連携の支援でご相談いただけます。

社内API・一般利用者向けAPIでAPIキーを持ち込まないほうがよい判断

社内システム同士の呼び出しなら、APIキーは要りません。IAM認可で呼び出し元のロールを特定でき、ステージのスロットリングで全体の上限は掛けられます。キーを足すと、配布と差し替えの手間だけが増えます。

スマートフォンアプリやブラウザから一般利用者が直接呼ぶAPIにも、APIキーは向きません。アプリに同梱したキーは取り出せる前提で考えるべきで、利用者ごとに配れば1万件の上限に当たります。この場合はCognitoなどのユーザー認証で守り、乱用対策はWAFのレートベースルールに任せます。HTTP APIで足りる要件なら、APIキーのためだけにREST APIへ移る判断もしません。

よくある質問

API GatewayのAPIキーと使用量プランについて、設定や運用でよく出る疑問をまとめました。

APIキーをヘッダーではなくクエリ文字列で受け取れますか？

API Gatewayが標準で読む場所はX-API-Keyヘッダーか、LambdaオーソライザーのusageIdentifierKeyの2つで、クエリ文字列は選択肢にありません。クエリで送る既存クライアントを残したい場合は、キーソースをAUTHORIZERにし、オーソライザーでクエリの値を読み取って返す方法になります。ただしクエリ文字列はアクセスログやブラウザ履歴に残りやすいため、新規の設計では避けてください。

APIキーの値を後から変更できますか？

変更できません。公式手順にも、作成後のキーの値は変えられないと書かれています。差し替えるときは新しいキーを作って同じ使用量プランに追加し、取引先の切り替えを確認してから古いキーを無効化または削除します。新旧2本を並行させる期間は、どちらの呼び出しも同じプランの別キーとして数えられるので、クォータが二重に使える点に注意してください。

使用量プランにキーを追加したのに403が返るのはなぜですか？

原因は3つに絞れます。キーをプランに追加した反映に数分かかっている、プランに対象のステージが結び付いていない、メソッドのAPIキー必須化の後に再デプロイしていない、のいずれかです。プランのapiStagesとキーの関連付けをget-usage-planとget-usage-plan-keysで確かめ、最後にステージへ再デプロイします。

クォータを超えたらどんなレスポンスが返り、いつ回復しますか？

クォータ超過のゲートウェイレスポンスはQUOTA_EXCEEDEDで、ステータスコードは429です。毎秒のスロットリングに当たったときも429ですが、こちらはTHROTTLEDで、トークンが補充されれば数秒以内に通る状態へ戻ります。クォータはperiodに指定した日・週・月の区切りで回復し、それまでに増枠が必要なときの手段は、update-usageによる今期の残数の書き換えです。両者の本文はゲートウェイレスポンスで別々に変えられます。