スコープ付きトークンへの移行

レガシートークンとは、impact.com のスコープ付きトークンが 2025 年 6 月に公開される前に作成されたトークンを指します。現在、impact.com API への認証にレガシートークンを使用している場合は、スコープ付きトークンへの移行時です。

レガシートークンは、すべての顧客向け API にわたって広範なアクセス権を付与するため、重大なセキュリティ上および運用上のリスクを伴います。スコープ付きトークンは、より安全で管理しやすい代替手段を提供します。詳細はこちらをご覧ください。 スコープ付きトークンのベストプラクティス.

移行手順

1. 現在の統合を評価する

まず、レガシートークンを使用している既存の統合（アプリ、スクリプト、サービス）をすべて特定します。新しいトークンを作成する前に、より新しい API バージョンに切り替えたときに何が変わる可能性があるかを理解しておく必要があります。

まず、各統合を一覧化し、その機能、アクセスする特定のエンドポイント、実行する操作の種類（読み取り、書き込み、またはその両方）、およびその統合の所有者または管理者を記録します。

次の間の重大な変更に特に注意してください API バージョン。確認すべき点は次のとおりです。

• 新しいバージョンではフィールド名の変更、データ型の変更、新しいフィールドの必須化が起こりうるため、リクエストのペイロードを確認してください。データ構造の不一致は、実行時エラーの一般的な原因です。
• レスポンスのペイロード構造を確認してください。フィールドが名前変更されたり、削除されたり、別の階層にネストされたりする可能性があり、その場合は API レスポンスを読み取るアプリケーションのロジックを更新する必要があります。

2. 新しいスコープ付きトークンを生成する

評価が完了したら、新しいスコープ付きトークンを生成できます。スコープ付きトークンの作成ガイドを使用してください。あなたが ブランド, パートナー、または エージェンシー.

評価結果に基づき、統合で使用するすべてのエンドポイントを一覧化し、次のような各操作を対応付けます。 GET, POST, PUT、または DELETE を、新しい API バージョンで対応する最小スコープにマッピングします。トークンを作成するときは、これらのきめ細かなスコープのみを割り当て、統合の特定の要件に合わせて調整します。

トークンを生成する際は対象の API バージョンを選択してください。これにより、認可される動作やデータ構造が決まります。影響を最小限に抑えるため、まずは統合ですでに使用しているバージョンに合わせ、別途後でアップグレードする計画にすることもできます。

最後に、目的と API バージョンを示す説明的な名前（例: Reporting_v2_Read-Only）をトークンに付け、新しい認証情報を安全に保存してください。

3. 統合をテストする

本番環境に移行する前に、ステージングまたは開発環境で更新した統合を十分にテストしてください。このテスト環境で統合コードを一時的に更新し、新しいスコープ付きトークンと新しい API ベース URL を使用するようにします。主要なワークフローをすべて実行し、データの読み取り、作成、更新、削除が期待どおりに動作することを確認します。

セキュリティテストの一環として、新しいトークンのスコープでカバーされていないエンドポイントへのアクセスを試してください。次の応答が返るはずです。 403 Forbidden エラーです。これはトークンがアクセスを正しく制限していることを確認します。影響評価に基づいて、リクエスト／レスポンスのロジックやフィールド名の更新など、コードの修正を行ったうえで再テストし、すべての機能が正しく動作するまで繰り返します。

4. 統合を更新する

テストが成功したら、変更を本番環境に展開する準備が整いました。検証済みのコード変更と構成更新をすべて本番コードベースに適用します。

ここで最も重要なのは、古いレガシートークンを新しいスコープ付きトークンに置き換えることです。新しいトークンが有効になったら、予期しないエラーが発生しないよう、統合とアプリケーションのログを注意深く監視してください。

5. 変更を周知する

新しい統合が問題なく動作していることを確認したら、最後に、使われていない古いレガシートークンを恒久的に取り消すか削除します。広範な権限を持つレガシートークンが侵害された場合、重大なリスクとなるため、これは重要なセキュリティ対策です。

最後に、内部ドキュメントを更新し、新しいトークンについて関係するチームメンバーに知らせてください。誤用を防ぎ、今後の円滑な運用を確保するために、管理方法も必ず文書化してください。