Migrate to Scoped Tokens

Legacy tokens refer to tokens created before the launch of impact.com’s scoped tokens in June 2025. If you currently use legacy tokens to authenticate with the impact.com APIs, it's time to make the shift to scoped tokens.

Legacy tokens grant broad access across all customer-facing APIs, which presents significant security and operational risks. Scoped tokens offer a more secure and manageable alternative. Read more about Scoped Token Best Practices.

Migration steps

1. Assess your current integrations

First, identify all existing integrations (apps, scripts, or services) that use a legacy token. Before creating new tokens, you should understand what might change when you switch to a newer API version.

Start by listing each integration and recording its function, the specific endpoints it accesses, the types of actions it performs (read, write, or both), and who owns or maintains the integration.

Pay close attention to any breaking changes between API versions. You should:

• Review your request payloads, as new versions might rename fields, change data types, or require new fields. Mismatched data structures are a common source of runtime errors.

• Examine the structure of response payloads, as fields may be renamed, removed, or nested differently, which will require updates to your application's logic for reading API responses.

2. Generate a new scoped token

Once your assessment is complete, you can generate a new scoped token. Use our guide to creating scoped tokens, whether you’re a brand, partner, or agency.

Based on your assessment, list every endpoint your integration uses and map each operation like GET, POST, PUT, or DELETE to its corresponding minimal scope in the new API version. When you create the token, you'll assign only these granular scopes, tailoring it to the integration’s specific needs.

Select the target API version when generating the token, as this dictates the behavior and data structures it will authorize. To minimize disruption, you could start by matching the version your integration already uses and plan a separate upgrade later.

Finally, give the token a descriptive name that indicates its purpose and API version (e.g., Reporting_v2_Read-Only) and securely save the new credentials.

3. Test your integration

Before going live, you should thoroughly test the updated integration in a staging or development environment. Temporarily update your integration's code in this test environment to use the new scoped token and the new API base URL. Execute all primary workflows to verify that data reads, creations, updates, and deletions work as expected.

As part of your security testing, try to access an endpoint that is not covered by the new token's scopes. You should receive a 403 Forbidden error, which confirms the token is correctly restricting access. After correcting any code based on your impact assessment, such as updating request/response logic or field names, re-test and iterate until all functions work correctly.

4. Update your integration

After successful testing, you're ready to deploy the changes to your production environment. Implement all validated code changes and configuration updates in your production codebase.

The most important step here is to replace the old legacy token with the new scoped token. Once the new token is active, closely monitor the integration and application logs to ensure that no unexpected errors occur.

5. Communicate the change

After confirming your new integration is running smoothly, it's time to permanently revoke or delete the old, unused legacy token. This is a crucial security step, as a compromised legacy token with broad permissions poses a significant risk.

To wrap up the process, update your internal documentation and inform relevant team members about the new token. Be sure to document how it's managed to prevent misuse and ensure smooth maintenance in the future.