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

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

レガシートークンは顧客向け API 全体への広範なアクセスを許可するため、重大なセキュリティおよび運用上のリスクをもたらします。スコープ付きトークンは、より安全で管理しやすい代替手段を提供します。詳細については [スコープ付きトークンのベストプラクティス](https://help.impact.com/other/ja/reference-documentation/api-access-tokens-and-changelog/scoped-tokens-best-practices).

#### 移行手順

<details>

<summary>1. 現在の統合を評価する</summary>

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

各統合を列挙し、その機能、アクセスする特定のエンドポイント、実行するアクションの種類（読み取り、書き込み、またはその両方）、および統合の所有者や保守担当者を記録することから始めてください。

特に注意すべきは、 [API バージョン](https://help.impact.com/other/ja/reference-documentation/api-access-tokens-and-changelog/api-changelog-summary)間の破壊的変更です。あなたは次のことを行うべきです：

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

</details>

<details>

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

評価が完了したら、新しいスコープ付きトークンを生成できます。当社のスコープ付きトークン作成ガイドを使用してください。あなたが [ブランド](https://app.gitbook.com/s/wMLlMoFBtKJa8ptd3zaw/account-administration/account-settings/api-tokens/create-an-api-access-token-as-a-brand), [パートナー](https://app.gitbook.com/s/b2rE79d9UhOKZQLgzSqx/account-management/account-settings/api-tokens/create-an-api-access-token-as-a-partner)、または [代理店](https://app.gitbook.com/s/okTNfAIjBtFchXJ9pC2q/account-settings/api-tokens/create-api-access-tokens-as-an-agency).

評価に基づいて、統合が使用するすべてのエンドポイントを列挙し、各操作（例えば `GET`, `POST`, `PUT`、または `DELETE` ）を新しい API バージョンの対応する最小スコープにマッピングしてください。トークンを作成する際には、これらの詳細なスコープのみを割り当て、統合の特定のニーズに合わせてください。

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

最後に、トークンには目的と API バージョンを示す説明的な名前（例: Reporting\_v2\_Read-Only）を付け、新しい資格情報を安全に保管してください。

</details>

<details>

<summary>3. 統合をテストする</summary>

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

セキュリティテストの一環として、新しいトークンのスコープに含まれていないエンドポイントへアクセスを試みてください。あなたは `403 Forbidden` エラーを受け取るはずであり、これはトークンが正しくアクセスを制限していることを確認します。リクエスト／レスポンスのロジックやフィールド名の更新など、影響評価に基づいてコードを修正した後、再テストと反復を行い、すべての機能が正しく動作するまで続けてください。

</details>

<details>

<summary>4. 統合を更新する</summary>

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

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

</details>

<details>

<summary>5. 変更を周知する</summary>

新しい統合が正常に稼働していることを確認したら、古く使用されていないレガシートークンを恒久的に無効化または削除する時です。広範な権限を持つレガシートークンが流出すると重大なリスクとなるため、これは重要なセキュリティ手順です。

プロセスを締めくくるために、社内ドキュメントを更新し、関連するチームメンバーに新しいトークンについて通知してください。誤用を防ぎ、将来の円滑な保守を確実にするために、管理方法を必ず記録してください。

</details>
