> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # API 認証情報のスコープと認証エラーのトリアージ > どの API キーがどのエンドポイントを呼び出せるのか、Withdraw を別の認証情報にしなければならない理由、Waffo が API キー・スコープ・署名・IP を確認する正確な順序、A0001 / A0002 / A0004 / A0046 の読み方、そして認証情報の変更が反映されるまでの時間について説明します。 認証の仕組みについては、すでに 3 つのページで説明しています。 | 質問 | ページ | | - | - | | リクエストへの署名、レスポンスと Webhook の検証、キーペアの生成はどう行いますか？ | [認証と署名 FAQ](/docs/ja/support/auth-signature-faq) | | 本番環境の公開鍵の提出やローテーション、API オペレーションタイプとは何ですか？ | [本番環境の公開鍵と API オペレーションタイプ](/docs/ja/support/production-api-key-and-public-key-faq) | | 通知 URL の設定、IP ホワイトリストの有効化、二段階認証の利用はどう行いますか？ | [Portal セルフサービスのセキュリティ設定](/docs/ja/support/portal-security-config-faq) | **このページはスコープ一覧とトリアージのフローチャートです** — どの認証情報が どのエンドポイントを呼び出せるのか、そして呼び出せないときに返されるエラーをどう読むかを説明します。 ## 関係するキーはいくつあり、それぞれ誰が保持するのですか？ 4 つあり、そのうちお客様が秘密に保つべきものは 2 つだけです。 | 項目 | 生成者 | 保持者 | 目的 | | - | - | - | - | | API キー | Waffo（受理された公開鍵ごとに発行） | お客様がすべてのリクエストに付与して送信 | リクエストがどの認証情報を — つまりどの加盟店・どのスコープを — 使っているかを識別する | | お客様の秘密鍵 | **お客様** | お客様（サーバー側のみ） | お客様のリクエストと Webhook レスポンスに署名する | | お客様の公開鍵 | お客様（Waffo に提出） | Waffo | お客様の署名を検証する | | Waffo の公開鍵 | Waffo | お客様が Portal からコピー | Waffo のレスポンスと Webhook の署名を検証する | 運用上重要な関係は次の 1 点です。**1 つの API キーは、ちょうど 1 つの公開鍵に対応します。** 送信した `X-API-KEY` によって、署名がどの公開鍵に対して検証されるかが決まります。 つまり API キーと秘密鍵はペアであり、片方だけを入れ替えると失敗します。 ## Integration ページに複数の API キーと公開鍵が表示されるのはなぜですか？どれを使えばよいですか？ 認証情報はオペレーションの種類ごとにスコープが区切られており、利用する種類ごとに 1 つずつ保持するためです。 使うべき行は、**API Operation Type** が実行しようとしている呼び出しに一致するものです。 各種類がどのエンドポイントを正確にカバーするかは以下のとおりです。 | オペレーションタイプ | 呼び出せるエンドポイント | | - | - | | **Payin** | `/api/v1/order/create`, `/api/v1/order/inquiry`, `/api/v1/order/cancel`, `/api/v1/order/refund`, `/api/v1/order/capture`, `/api/v1/refund/inquiry`, `/api/v1/subscription/create`, `/api/v1/subscription/inquiry`, `/api/v1/subscription/cancel`, `/api/v1/subscription/manage`, `/api/v1/subscription/change`, `/api/v1/subscription/change/inquiry`, `/api/v1/subscription/update`, `/api/v1/tokenization/generate`, `/api/v1/tokenization/inquiry`, `/api/v1/tokenization/remove`, `/api/v1/merchantconfig/inquiry`, `/api/v1/paymethodconfig/inquiry`, `/api/v1/saved-payment-methods/config`, `/api/v1/userid/inquiry`, `/api/v1/userinfo/inquiry`, `/api/v1/wallet/inquiry`, `/api/v1/chargeback/inquiry`, `/api/v1/chargeback/list`, `/api/v1/chargeback/update`, `/api/v1/chargeback/accept`, `/api/v1/fraud-report/list`, `/api/v1/risk/transactionlimit/create`, `/api/v1/risk/transactionlimit/update`, `/api/v1/risk/transactionlimit/inquiry` | | **Payout** | `/api/v1/payout/create`, `/api/v1/payout/inquiry`, `/api/v1/account/balance/inquiry` | | **Payin and payout** | 上記 2 行のすべて | | **Withdraw** | `/api/v1/withdraw/consult`, `/api/v1/withdraw/create`, `/api/v1/withdraw/inquiry`, `/api/v1/account/balance/inquiry`, `/api/v1/account/history/inquiry` | | **Card collection** | `/cardcenter/web/v1/tokenization/submit` — ブラウザ側のカード情報送信エンドポイント | この表から確定する 2 つの細部があります。 * **残高照会は Payout スコープと Withdraw スコープの両方に含まれます。** どちらの認証情報でも 到達できる唯一のエンドポイントであり、残高確認のためにスコープを追加する必要が生じないのはこのためです。 * **アカウント履歴は Withdraw 専用です。** Payout の認証情報では読み取れません。 ## Payin のキーを Payout のエンドポイントで使ったら権限エラーになりました。なぜですか？ スコープは加盟店単位ではなく、リクエストパス単位で適用されるためです。認証情報自体は有効でしたが、 そのエンドポイントを呼び出す権限がなかっただけであり、リクエストは **`A0004` Permission denied**（HTTP 401）で拒否されます。 デバッグ時に覚えておくべき区別は次のとおりです。`A0004` は「このキーは正しいが、エンドポイントが違う」を意味します。 キーが間違っている、署名が間違っている、アカウントにその商品が含まれていない、という意味ではありません。 上の表でエンドポイントを探し、それを含むオペレーションタイプの認証情報の行を使用してください。 ## Withdraw を Payin や Payout と組み合わせられないのはなぜですか？両方必要なのですが。 出金は**お客様自身の精算済み資金を外へ移動させる**操作であり、Payin と Payout は顧客の資金を受け入れる、 または第三者へ支払う操作だからです。出金を独立した認証情報に分けておくことで、チェックアウトサービスや 送金サービスが保持するキーが残高の引き出しに使われることは決してなく、片方の漏洩が他方の漏洩を意味しなくなります。 Portal は警告ではなく強制でこれを実現します。Withdraw を選択すると Payin と Payout の選択が解除され、 Payin または Payout を選択すると Withdraw の選択が解除されます。 そのため、API 経由で出金を行う場合は、**少なくとも 2 つの認証情報**を用意してください — 決済トラフィック用に 1 つ、出金用に別途 1 つ — そして、シークレットマネージャー内では別の場所に、 異なるアクセスリストで保管してください。それが分離の目的であり、両方を同じ環境ファイルに置いてしまえば 分離の意味が失われます。2 つ目の認証情報の提出は、1 つ目と同じセルフサービスのフローです。 [本番環境の公開鍵と API オペレーションタイプ](/docs/ja/support/production-api-key-and-public-key-faq) を参照してください。 ## API キー・スコープ・署名・IP はどの順序で確認されるのですか？ 以下の順序です。この順序を知っていれば、複数の問題が同時にある場合にどのエラーが最初に返るかがわかります。 1. **`X-API-KEY` が存在するか？** なければ → `A0001`。 2. **既知の `Active` な認証情報か？** そうでなければ → `A0001`。 3. **その認証情報のオペレーションタイプがこのエンドポイントを許可しているか？** していなければ → `A0004`。 4. **`X-SIGNATURE` がその認証情報の公開鍵で検証できるか？** できなければ → `A0002`。 5. **ホワイトリストを有効にしている場合、送信元 IP がリストに含まれているか？** 含まれていなければ → `A0046`。 実務上の帰結は次のとおりです。**署名が誤っており、かつホワイトリスト外の IP から送信されたリクエストは、 `A0046` ではなく `A0002` を返します。** したがって、`A0046` を見たことがないからホワイトリストは問題ないと 結論づけないでください — 単に署名チェックを通過したことがないだけかもしれません。上記の順序でエラーを修正してください。 ## 「invalid API key」と「invalid signature」の違いは何ですか？ 同じペアの異なる半分を指しており、それぞれに固有の確認項目があります。 | コード | メッセージ | HTTP | 意味 | 確認事項 | | - | - | - | - | - | | `A0001` | Invalid Api secret key | 401 | `X-API-KEY` が欠落している、未知である、または現在 `Active` ではない | ヘッダーは付いているか？ **この**環境の Integration ページからコピーしたか？ キーのバージョンは `Pending` や `Rejected` ではなく `Active` か？ | | `A0002` | Invalid signature | 401 | その API キーに紐づく公開鍵で署名を検証できなかった | 送信するバイト列そのものに、**その** API キーの公開鍵とペアになる秘密鍵で、SHA256withRSA で署名し、Base64 エンコードしたか？ | | `A0004` | Permission denied | 401 | 認証情報は有効だが、そのオペレーションタイプでは呼び出せないエンドポイント | 上のスコープ表 | | `A0046` | Access denied: the request IP is not in the whitelist | 401 | 署名は問題なし。送信元 IP がホワイトリストに含まれていない | 現在の送信元（egress）IP と、ホワイトリストのエントリ | キーのローテーション後の `A0002` は、ほぼ常に `X-API-KEY` と署名用秘密鍵が対応しなくなったことを意味します — 両方を 1 回の変更として同時に切り替えてください。 ## 「merchant status abnormal」や「contract does not allow this operation」は認証の問題ですか？ いいえ。これらはアカウントおよび契約の状態であり、認証情報が受理された**後**に返されます。 | コード | 意味 | 確認場所 | | - | - | - | | `A0006` | Merchant status abnormal | お客様のアカウント状態 — インテグレーションサポートにお問い合わせください | | `A0010` | Operation not allowed in merchant contract | お客様の契約にこのオペレーションまたは商品が含まれていない | | `A0018` | The payment method in the order does not match your contract | その国・通貨で契約済みの決済手段 | トリアージの近道：`A0001` / `A0002` / `A0004` / `A0046` はすべてお客様自身で修正できる*認証情報*の問題です。 `A0006`、`A0010`、`A0018` は\*権限（エンタイトルメント）\*の問題であり、Waffo 側での設定変更か、 別のリクエストが必要です。完全な一覧は [エラーコード](/docs/ja/developer-docs/tools-and-references/developer-tools/error-codes) を参照してください。 ## API バージョンヘッダーは必ず送信する必要がありますか？ はい。生の HTTP 呼び出しでは `X-API-VERSION: 1.0.0` を送信してください。SDK はこのヘッダーを 自動で管理するため、SDK 側では設定や上書きをしないでください。 変更履歴から誤解しやすいため、あえて挙げておく落とし穴があります。API バージョン履歴に表示される バージョン番号は**ドキュメントおよび契約のリビジョン**を識別するものであり、このヘッダーで送信してはいけません。 ヘッダーの値は `1.0.0` です。[API 概要](/docs/ja/developer-docs/integration/api/overview) を参照してください。 ## キーを有効化またはローテーションしてから、どれくらいで使えるようになりますか？ **しばらく**お待ちください — 即時ではありません。署名を検証できるのは `Active` な認証情報のみで、 リクエストパスで使われる参照は一定間隔で更新されます。そのため、`Active` になった直後のキーは短時間拒否される ことがあり、逆に有効でなくなった直後のキーは同じ時間だけまだ使える場合があります。 ローテーションの手順としては、新しいバージョンが `Active` になった後、この時間が経過するまで待ってから トラフィックを切り替え、新しい認証情報が実トラフィックで検証できるまで古い認証情報を残しておいてください。 複数のバージョンを同時に `Active` にできるため、どちらも使えない空白期間を作る必要はありません。 IP ホワイトリストの挙動はこれとは異なり、より速く反映されます — 後述を参照してください。 ## 1 つの API キーを複数の加盟店アカウントで使えますか？ いいえ。各 API キーは 1 つの加盟店アカウントに属し、アカウント A の認証情報で認証されたリクエストは アカウント A のデータに対してのみ操作できます。アカウント B に属する注文を照会すると、キー自体は完全に有効でも失敗します。 複数の加盟店 ID を運用している場合は、アカウントごとに認証情報のセットを 1 つずつ保持し、常にそのオブジェクトを 作成したアカウントの認証情報で呼び出してください。このルーティングを最初から組み込んでおくほうが、後から 組み替えるよりはるかに低コストです。[マルチブランドとサブ加盟店の構成](/docs/ja/support/multi-brand-and-sub-merchant-faq) を参照してください。 ## IP ホワイトリストにはどんな形式が登録でき、編集はどれくらいで反映されますか？ | 項目 | ルール | | - | - | | エントリ形式 | **IPv4 アドレスと IPv4 CIDR レンジ** — 例：`203.0.113.7` や `198.51.100.0/24` | | IPv6 | 非対応 | | ホスト名 | 非対応 — アドレスとレンジのみ | | 加盟店あたりのエントリ数 | 最大 **20** 件。重複は拒否 | | エントリごとの制御 | ラベルと、個別のオン/オフ切り替え | | マスタースイッチ | 有効なエントリが 1 つもない状態ではオンにできない。最後の有効なエントリを削除または無効化するとオフになる | | 反映までの時間 | **ほぼ即時** — 保存時にキャッシュされた参照も無効化される | 20 件では足りない場合は、個々のホストを列挙するのではなく CIDR レンジにまとめてください — `/24` 1 つで 最大 254 件のエントリを置き換えられ、安定したレンジはスケールアウトのたびに変わるリストより保守も楽です。 有効化の方法と Portal の各項目は [Portal セルフサービスのセキュリティ設定](/docs/ja/support/portal-security-config-faq) を参照してください。 ## サーバーがプロキシの背後にある、または動的 IP を使っています。実際には何が照合されるのですか？ 照合されるアドレスは、リクエストが Waffo に到達した時点での **forwarded-for チェーンの先頭エントリ**です — つまり最終ホップではなく、発信元クライアントのアドレスです。この値が IPv4 アドレスとして解釈できない場合、 チェックは「不一致」ではなく「判定不能」として扱われます。 この区別が結果を左右し、適用ポリシーは 3 種類あります。 | ポリシー | 送信元 IP がリストにない | 送信元 IP が判定不能 | | - | - | - | | 観測のみ（Observe only） | 許可し、記録する | 許可し、記録する | | 強制（Enforce、デフォルト） | `A0046` で**ブロック** | 許可し、記録する | | 厳格（Strict） | `A0046` で**ブロック** | `A0046` で**ブロック** | Portal で操作できるのはマスターのオン/オフスイッチだけで、ポリシー自体は Waffo が設定します。 そのため、送信元 IP が動的、マルチリージョン、または多層構成のコンテナ環境の背後にある場合は、 まずインテグレーションサポートに**観測のみ**への設定を依頼し、記録された不一致を確認したうえで、 リストが完成してから強制に切り替えてください。何も確認せずに強制をオンにすることが、正しく設定された インテグレーションが障害を起こす典型パターンです。 送信元 IP を一定のレンジに固定することが本当に不可能な場合、ホワイトリストはお客様に適した制御ではありません — これは任意の機能でデフォルトはオフであり、署名検証はすべてのリクエストで既に必須になっています。 ## 自分の送信元（egress）IP はどうやって調べればよいですか？ Waffo からは調べられません — Waffo が見るアドレスはお客様のインフラが提示するアドレスであり、 それを確実に知る情報源はお客様自身のプラットフォームです。クラウド環境の NAT ゲートウェイや ロードバランサーの設定であり、これが安定が保証される唯一の場所でもあります。 設定から取得できない場合の実務的な方法が 2 つあります。 * **決済サービスが稼働する環境の egress レンジをプラットフォームチームに確認し**、観測したアドレスではなく レンジをホワイトリストに登録してください。観測したアドレスは、次にスケールしたときに古くなります。 * 上述のとおり**まず観測のみで運用し**、何かがブロックされる前に、不一致の記録そのものからどのアドレスが 使われているかを把握してください。 ## Portal のパスワードは通信中に暗号化されていますか？Waffo のスタッフに見えますか？ パスワードは TLS に加えて、Waffo の公開鍵を使って**送信前にブラウザ内で暗号化**されます — そのため、 フォームが平文のパスワードを回線に載せることはなく、暗号化されたチャネルの中であっても平文は流れません。 パスワードの設定や変更時も同様です。 保存側では**一方向ハッシュ**としてのみ保持されるため、読み出せる復元可能なコピーは存在しません。 Waffo の誰もお客様のパスワードを取得できず、パスワードリセットでは旧パスワードを伝えるのではなく リンクが発行されます。 パスワードのルール、有効期限、ロックアウト、サインイン履歴については [Portal サインイン、リンク、アカウント状態](/docs/ja/support/portal-account-access-faq) と [加盟店 Portal の運用](/docs/ja/support/portal-operations-faq) を参照してください。 ## 秘密鍵が漏洩したかもしれません。何をどの順番で行えばよいですか？ まずローテーション、調査はその後です — そして、漏洩した秘密鍵があれば誰かがお客様として リクエストに署名できるということを忘れないでください。文字どおり深刻な事態です。 1. **新しいキーペアを生成し**、Portal から新しい公開鍵を提出します。審査中も既存の認証情報は 引き続き動作するため、この手順でダウンタイムは発生しません。 2. **新しいバージョンが `Active` になったら、Integration ページでその API キーを確認し**、 `X-API-KEY` と署名用秘密鍵を同時に切り替えます。 3. **古い認証情報の使用を停止し**、自社のログで古い API キーを付けたトラフィックが残っていないことを確認します。 4. まだであれば **IP ホワイトリストを有効にします**。盗まれた認証情報をお客様のインフラ外から使えなくする 唯一の制御であり、必要になる前に設定しておくべき理由でもあります。 5. **自社での取り扱いを見直します**。秘密鍵をソース管理、イメージ、ログ、ブラウザに置いてはいけません。 [本番稼働チェックリスト](/docs/ja/developer-docs/getting-started/go-live) では、環境設定または 鍵管理サービスに保管することを求めています。 6. **インテグレーションサポートに、何がいつ起きたかを伝えます**。Waffo 側で古い認証情報の アクティビティを確認できるようにするためです。 手順 2 の失敗パターンは最も多いため注意してください。新しいキーペアに古い API キーを組み合わせると、 古い公開鍵に対して検証が行われるため、Portal 上は正しく設定されているように見えても新しい署名は失敗します。 ## 署名の問題をデバッグするために、リクエストとレスポンスのペイロードを記録してもよいですか？ はい。むしろ記録すべきです — ただし、パースして再シリアライズしたコピーではなく**生のバイト列**を 記録してください。JSON ライブラリを一往復させること自体が、署名が検証できない主要な原因の 1 つだからです。 記録すべきもの、記録してはいけないもの： | 記録する | 記録しない | | - | - | | 署名した正確なリクエストボディのバイト列 | 秘密鍵、またはその一部 | | 生成した `X-SIGNATURE` | カード番号全体やその他の機密性の高い決済データ | | どの認証情報を使ったか判別できる程度にマスクした `X-API-KEY` | API キー全体 | | 返されたレスポンスコードとエラーコード | | 本番稼働チェックリストでは、2 列目は助言ではなく要件です。ログにキー全体や機密性の高い決済情報を 記録してはいけません。短期間かつアクセス制御されたデバッグ用の記録がこの用途に適した形であり、 恒久的なログ行にすべきではありません。 *** This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.