HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides
ChangelogHelp CenterCommunityContact Us

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

If your app is a standalone app, ensure your installation flow addresses the scenario below:

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.
  1. The user is redirected to your app’s login page.
  2. The user logs in and is redirected to the Klaviyo OAuth installation flow.
The user is not logged in to your app and does not have an account.
  1. The user is directed to your app’s login page where they can create an account.
  2. The user creates an account and logs in.
  3. The user is redirected to the Klaviyo OAuth installation flow.
Your app is a multi-tenant app, i.e., each tenant (or sub-account) operates independently, and a sub-account must be provided.
  1. The user is redirected to a page to provide the sub-account for installing the app. For example, this may be a dropdown of available accounts to select from or a text box requesting a specific store URL.
  2. After the sub-account has been identified, the user is redirected to the Klaviyo OAuth installation flow.

Embedded app installation flow

If your app is an embedded app (e.g., apps hosted on ecommerce platforms), ensure your installation flow addresses the scenarios below:

Scenario Flow step(s)
The user is logged in to the host platform.
  1. The user directly enters the Klaviyo OAuth installation flow.
The user is not logged in to the host platform but has an existing account.
  1. The user is redirected to the host platform's login page.
  2. After login, the user is redirected to the Klaviyo OAuth installation flow.
The user is not logged in to the host platform and does not have an account.
  1. The user is redirected to the host platform’s login page, where they can create an account.
  2. The user creates an account and logs in.
  3. The user is redirected to the Klaviyo OAuth installation flow.
The user has not installed the app on the host platform.
  1. A message informs the user that they need to install the app from the host platform's app listing page and retry installation.
  2. The user is redirected to the Klaviyo OAuth installation flow.
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.
  1. The user is redirected to a page to provide the sub-account for installing the app. For example, this may be a dropdown of available accounts to select from or a text box requesting a specific store URL.
  2. After the sub-account has been identified, the user is redirected to the Klaviyo OAuth installation flow.

The user has already installed the app on its host platform

Scenario Flow step(s)
The user is logged in to the host platform.
  1. The user directly enters the Klaviyo OAuth installation flow.
The user is not logged in to the host platform but has an existing account.
  1. The user is redirected to the host platform's login page.
  2. After login, the user is redirected to the Klaviyo OAuth installation flow.
The user is not logged in to the host platform and does not have an account.
  1. The user is redirected to the host platform’s login page, where they can create an account.
  2. The user creates an account and logs in.
  3. The user is redirected to the Klaviyo OAuth installation flow.
The user has not installed the app on the host platform.
  1. A message informs the user that they need to install the app from the host platform's app listing page and retry installation.
  2. The user is redirected to the Klaviyo OAuth installation flow.
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.
  1. The user is redirected to a page to provide the sub-account for installing the app. For example, this may be a dropdown of available accounts to select from or a text box requesting a specific store URL.
  2. After the sub-account has been identified, the user is redirected to the Klaviyo OAuth installation flow.

The user has not installed the app on its host platform

❗️

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.

ScenarioFlow 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 20 days ago

Power smarter
digital relationships
By entering your information and clicking “Sign up,” you consent to receive marketing emails (such as newsletters, blog posts, webinars, event invitations and new product updates) from Klaviyo from time to time. You can unsubscribe at any time by clicking on the “Unsubscribe” link at the bottom of our emails. For more information on how we process your personal information and what rights you have in this respect, please see our Privacy Policy.
Terms and Privacy Trademarks Security