Update your OAuth scopes

If you need to update the scopes for your OAuth app, follow these steps to maintain proper functionality and ensure a smooth transition for your users.

How to update your scopes

To update the scopes for your OAuth app, you’ll need to make changes in your OAuth app settings and authorization request flow.

Update your OAuth app settings

1. Navigate to the app management page.
2. Click the 3 dots next to the app you’d like to update, then select Edit.
3. Update the Scopes field as needed; see a list of available scopes for each API.

4. When you’re done, click Save.

Update your app’s authorization request flow

You must include any new scopes in your query parameters when redirecting your app URL to https://www.klaviyo.com/oauth/authorize. Reference the App URL redirects to the Klaviyo authorization page step for more information. Ensure that when you test your app’s new authorization request flow, you are prompted to grant permissions for the updated scopes.

How installations are handled after updating

Once you have updated your scopes, new installations of your app will request the updated permissions from users. Apps published on Klaviyo’s Integrations Directory will update automatically when scopes are updated, so no resubmission is required.

Existing installations will retain the old scopes until the user reauthorizes the app with the new scopes. We recommend sending customers an email notification prompting them to reauthorize the app with the new scopes (using the new OAuth authorization URL). You can also add an indicator in your app prompting the user to update to access new functionality.

Authorization error handling

Even if you send an email notifying users to reauthorize your app with the new scopes, there is no way to ensure they reauthorize. To maintain backwards compatibility for your users who haven’t updated, you will need to handle 403 errors related to scopes effectively. These errors can occur when a merchant's existing authorization does not include your app’s newly-added scopes.

Here's what you can do:

• Monitor your application for 403 errors related to scope issues.
• When a 403 error occurs, you can notify the affected user that they need to reauthorize your app to access the new permissions.
  • You may want to store the last time you notified the customer to avoid spamming them.
• Provide clear instructions on how users can reauthorize your application within their Klaviyo account. For example, “We’ve improved our Klaviyo application. For access to the most up-to-date functionality, please follow [link to your app URL which redirects to the updated authorization request].”

By following these steps, you can successfully update your OAuth application with Klaviyo, extend the necessary scopes, and ensure a user-friendly experience for both new and existing users.

Eventually, you may want to revoke applications that are too far out of date, in which case you should follow our Revoke an application instructions.

Additional resources

• Set up OAuth
• Submit your app for review
• Create help docs for your integration