会社のシステムからSaaSへデータをつなぐときは、「会社の処理として使うのか」「社員本人の代わりに使うのか」から考えると、APIキーとOAuth 2.0の違いが分かります。
使える方式は接続先の仕様で決まります。この記事では、3つの業務例とデータを渡す順番を比べ、発注前に決めたい権限・保管・停止時の対応を整理します。APIは、別のシステムとデータをやり取りするための窓口です。
APIキーとOAuth 2.0の違い
どちらが向くかを具体例で比較する
以下は方式を考えるための架空例です。実際に使える方式は接続先SaaSの仕様で決まります。APIキーの権限もサービスによって異なるため、「APIキーなら広い権限」「OAuthなら安全」と一般化しません。
表は左右にスクロールして比較できます。
| ケース | まず検討する方式 | 見落とせない条件 |
|---|---|---|
| 会社のバッチが共有データを毎晩取得 | 提供元が許可するサーバー間認証 | 接続に使う秘密情報の保管・更新方法と、与える権限 |
| 社員ごとに本人の予定表を読む | 利用者が権限を委任するOAuthフロー | 同意範囲、撤回、退職時の失効、トークン更新 |
| 取引先ごとに別のSaaS環境へ接続 | 接続先ごとの仕様と管理方式を確認 | テナント分離、審査、利用者・管理者同意 |
APIキーは、提供元がアプリやプロジェクトを識別し、利用量やアクセスを管理するために発行する値です。サーバー側で秘密に保管するキーと、ブラウザ等で利用され閲覧可能になることを前提としたキーがあります。後者も無制限に公開してよいわけではなく、提供元の仕様に沿って利用元やAPI、利用量を制限します。
利用者の本人確認やデータへの権限を、キーだけでどこまで判断できるかもサービスごとに異なります。
OAuth 2.0は、アプリに許可するアクセス権限を定め、アクセストークンでAPIを利用するための認可の枠組みです。利用者の権限を委任する方式のほか、サービスが提供するサーバー間の方式もあります。APIキーかOAuthかだけで安全性は決まりません。
接続先が対応する方式と、必要な操作・権限・失効方法を確認します。なお、誰であるかを確かめる「認証」と、何をしてよいかを決める「認可」は別です。OAuth 2.0だけを本人確認の仕様と考えないでください。
たとえばマネーフォワード クラウドの開発者向け資料は、同社APIでのAPIキーとOAuth 2.0の利用場面・権限範囲の違いを明示しています。ただしその説明は同社の実装に固有であり、すべてのSaaSへそのまま当てはめてはいけません。
方式を選ぶ前に確認する6項目
- 操作主体：固定された企業システムか、各利用者の代理操作か。
- 権限範囲：読むだけか、更新や削除も必要か。最小権限を指定できるか。
- 保管場所：秘密管理を前提とするAPIキーやclient secretを、ブラウザや公開リポジトリへ置かず安全に管理できるか。公開利用を前提とするキーは、提供元が求める利用制限を設定できるか。
- 期限と失効：トークン更新、担当者退職、連携解除、漏えい時のローテーションに対応できるか。
- 監査：誰がいつどのデータへアクセスしたかを追えるか。
- 障害対応：認証失敗時の再認可、処理の再試行、重複防止、未処理データの照合をどう行うか。
認可コード方式とPKCEで確認すること
- アプリから接続先の認可画面へ送り、必要なスコープ（許可を求める操作の範囲）を提示する。接続先が利用者を認証し、必要に応じて同意を求めます。
- 事前登録したリダイレクト先（接続先から戻るURL）で認可コードを受け取る。
- アプリがコードをトークンへ交換し、取得した権限の範囲でAPIを呼ぶ。秘密情報を保持できるサーバー構成では、トークン等を安全に管理します。
- 権限不足、期限切れ、同意取消しを区別し、必要な再認可や担当者への通知につなげる。
PKCEは、認可要求とコードの交換を結び付け、盗まれたコードの不正な利用や、別のコードを差し込む攻撃を防ぐための仕組みです。アプリは毎回生成した検証用の値からチャレンジを作って送り、コード交換時に元の値を提示します。利用者の本人確認や、アクセス権限の付与をPKCEだけで行うわけではありません。
IETF RFC 9700の2.1.1節は、秘密情報を安全に保持できない公開クライアントの認可コードフローではPKCEを必須とし、サーバー側で秘密情報を保持する機密クライアントにも推奨しています。チャレンジは要求ごとに変え、S256方式を使います。リダイレクト先の検証や、フローに応じたCSRF対策も確認します。
発注前に、接続先が推奨するフローとライブラリ、トークン更新・失効の仕様、検証環境、同意画面の審査要否を確認してください。ユーザーのパスワードを連携システムが直接預かる方法で代用しません。
「認証できた」だけでは運用テストが足りない
架空の請求データ連携を考えます。初日は正常に読めても、30日後に期限切れで同期が止まれば業務上は失敗です。テストでは正常な読み取りに加え、権限不足、トークン失効、同意取消し、接続先の一時停止を個別に再現し、最後にいつ成功したか、どのデータが未処理かを運用画面またはログで追えるか確認します。
APIキー方式でもローテーション中に旧キーと新キーが混在することがあります。停止時間を避ける手順、失効後に残るジョブ、監査ログを設計しておきます。費用比較では初期実装だけでなく、審査、権限変更、障害復旧、継続運用を別項目にします。
認証エラーが出たら、どこから確認するか
「連携できない」という報告だけでは復旧できません。APIの返答、最後に成功した時刻、処理されなかったデータの範囲を分けます。以下は一般的な切り分け例です。実際のHTTPステータスとエラー本文の意味は、接続先サービスの公式仕様を優先してください。
表は左右にスクロールして比較できます。
| 見える症状 | 先に確かめること | 復旧時の注意 |
|---|---|---|
| 401・期限切れ | キー失効、トークン有効期限、更新処理 | 再認可後、未処理分だけを照合する |
| 403・権限不足 | スコープ、利用者/組織の権限、同意取消し | 権限を無制限に広げず必要範囲を確認 |
| 429・呼び出し制限 | 接続先の制限値、再試行間隔 | 一斉再送で重複や追加制限を起こさない |
| 応答不明 | 接続先に処理済みか、連携IDと更新時刻 | 同じ更新を盲目的に再送しない |
たとえば夜間同期で401が発生したとします。管理画面で連携状態が「停止」と分かっても、どの顧客データまで同期済みかは別問題です。最終成功時刻と連携IDを確認し、再認可後に不足分を照合します。接続先が更新要求を受け取ったか分からないときは、再送前に取得APIや管理画面で状態を確認します。
開発会社へ渡すと見積が具体的になるメモ
- 接続先SaaS名と、使いたい公式API・利用契約
- 誰の操作として実行するか（会社のバッチか、各社員の代理か）
- 読む/書く/削除する対象と、必要な最小権限
- 連携の頻度、件数、許容できる遅延
- 失効・退職・解約時に誰が再認可するか
- 失敗したデータを追跡し、重複なく復旧する方法
接続先がAPIキーとOAuthの両方を提供していても、機能ごとに使える方式や審査条件が違う場合があります。まず公式仕様と契約範囲を確認し、方法を決めてから、認証実装・障害処理・運用手順を分けて見積もります。
Microsoft Graphの例で、権限の違いを確かめる
実際のサービスでは「OAuthを使うか」だけでなく、誰としてAPIを呼ぶかが選択の中心です。Microsoft Graphの公式の権限説明では、サインイン中の社員を代理する「委任されたアクセス」と、社員のサインインなしにアプリ自身として動く「アプリのみのアクセス」を分けています。
次は設計を始めるための架空の業務例であり、クラウドシードの導入実績ではありません。
表は左右にスクロールして比較できます。
| したいこと | 最初に調べる権限 | 確認する運用条件 |
|---|---|---|
| 社員が自分の予定を業務画面で見る | 委任されたアクセスで利用可能な権限 | 本人の同意、退職・権限変更時の扱い |
| 夜間に組織の対象データを同期する | アプリのみのアクセスがそのAPIで許されるか | 管理者の同意、対象範囲の制限、秘密情報の更新 |
アプリのみの権限は、サインイン利用者がいなくても動く一方、組織内の広いデータへ届く設定になり得ます。自動処理だからと広い権限を先に与えず、接続先APIに必要な最小権限と、対象データを絞れる条件を公式の権限一覧で確認します。
担当者へは「接続方式」だけでなく、誰のデータをいつ取得し、同意や認可が取り消されたらどの処理を止めるかまで伝えてください。
見積もりとテストで差が出る部分
APIキー方式でも、発行・保管・更新・監査は必要です。OAuth方式ではさらにアプリ登録、同意画面、リダイレクト、トークン更新と失効への対応が発生し得ます。費用は方式名だけでなく、接続サービスの仕様、利用者数、同期方向、データ件数、失敗時の復旧条件で変わります。
既存記事「API・SaaS連携費用の見積項目」で、認証以外の費用要因も整理しています。
テストでは、有効・期限切れ・権限不足・同意取消し・接続先停止を分けて試します。更新系APIなら同じ要求を再送した際の重複も確認します。再送と照合の設計は「API連携でデータが重複・欠落する場合の対策」につながります。
現在のシステムや接続先の仕様を確認したうえで開発方法を相談したい場合は、システム開発の相談窓口で対応範囲を確認できます。接続可否を無条件に保証するものではありません。
