Handle your app's OAuth flow
Learn best practices for handling your app’s OAuth installation flow.
Before you begin
Before getting started, you should have created your app and ensured that your app can successfully initiate an OAuth connection.
You will learn
After following our Make API calls using OAuth guide, you should have successfully received an access token which grants your app access to make API calls on the user’s behalf. This article covers how to identify and handle your app’s OAuth installation and uninstallation flows initiated from your app’s side and from Klaviyo’s side. You will learn about:
- Standalone and embedded app installation flows
- Installation error handling
- Uninstallation flows
- Rate limits
Handling your app’s OAuth flow
We expect that your app installations can be initiated from within your app’s platform. Additionally, when a user navigates to your app listing in Klaviyo and clicks Install, the installation process must properly function on Klaviyo’s end. We require that your OAuth installation flow works on both your app's side and Klaviyo's side to ensure a seamless and consistent user experience.
When a user tries to install your app from Klaviyo, your OAuth installation flow should ensure that the user is logged in to your app's host platform before directing them to OAuth installation. Follow the installation flow below that matches your app's type.
Standalone app installation flow
For standalone apps, ensure your installation flow addresses these scenarios for users installing from Klaviyo:
| Scenario | Flow step(s) |
|---|---|
| The user is logged in to your app. | The user directly enters the Klaviyo OAuth installation flow. |
| The user is not logged in to your app but has an existing account. |
|
| The user is not logged in to your app and does not have an account. |
|
| Your app is a multi-tenant app, i.e., each tenant (or sub-account) operates independently, and a sub-account must be provided. |
|
Embedded app installation flow
For embedded apps (e.g., apps hosted on ecommerce platforms), ensure your installation flow addresses these scenarios for users installing from Klaviyo:
| Scenario | Flow step(s) |
|---|---|
| The user is logged in to the host platform. |
|
| The user is not logged in to the host platform but has an existing account. |
|
| The user is not logged in to the host platform and does not have an account. |
|
| The user has not installed the app on the host platform. |
|
| Your app's host platform is a multi-tenant app, i.e., each tenant (or sub-account) operates independently, and a sub-account must be provided. |
|
Users installing your app from Klaviyo should not be redirected elsewhere to initiate the installation flow. Apps that only have an OAuth installation flow set up from their own platform will be rejected.
Installation errors
Your app should also handle installation errors in which a user denies permissions or leaves the installation page, resulting in an installation failure.
| Scenario | Flow step(s) |
|---|---|
| The user denies the permissions needed to install your app. | The user receives an error message indicating that the app installation failed due to denied permissions. The message allows them to dismiss it, and they can attempt installation again later. |
| The user leaves the OAuth page and returns to install your app after the authorization code has expired (after 5 minutes). | The user receives an error message indicating that the session is no longer valid. The message redirects them to re-attempt installation. |
If a user needs to take manual, avoidable steps to install your app, it will be rejected.
Uninstallation flow
In addition to the installation flow cases, make sure that your OAuth flow handles uninstalling your app from your app’s side and from Klaviyo’s side.
Uninstalling from your app's platform
When a user uninstalls your app from your platform, your app should make an API call to revoke any refresh and/or access tokens for the user. After this action, the app should be removed from the account’s integration page in Klaviyo, and the user can re-install it if they wish. Make sure that your app no longer displays the app as installed.
For a positive user experience, ensure that a disconnect option is easy to locate in your app's UI.
Uninstalling from Klaviyo
When a user uninstalls your app from Klaviyo, ensure that the status reflects properly in your app, i.e., it appears as uninstalled on your app’s platform.
Rate limits
To avoid unnecessary load in accordance with our API Terms of Use, your app must respect API rate limits. Rate limiting for OAuth apps differs from our standard API rate limiting. While private key integrations share the same limit quota per account, OAuth apps:
- Receive their own rate limit quota per installed app instance (i.e., per account per app).
- Receive rate limit response headers for API calls that are specific to the app instance’s quota
For example, the Create Events endpoint has an XL (3500/m) rate limit. Say that a given Klaviyo account:
- Has a private key integration, PK Integration A. PK Integration A can make calls to Create Events with a steady rate limit of 3500/m.
- Installs OAuth App 1. OAuth App 1 will have access to a 3500/m Create Events rate limit, totally isolated from Integration A’s usage.
- Installs OAuth App 2. OAuth App 2 would receive a 3500/m rate limit, in isolation from the OAuth App 1 and the PK Integration A.
Next steps
Once that your app handles its OAuth flow correctly for each client state (logged in vs. not logged in) from your app’s side and Klaviyo’s side, follow our guide that covers best practices and common errors in the app review process to pass your app review.
Additional resources
Updated about 17 hours ago