HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides

Build a user-scoped app

Learn when to build a user-scoped OAuth app, how to create one, and how to handle per-user tokens, scopes, and revocation.

By default, every Klaviyo OAuth app is company-scoped: it's installed once per account, acts for the whole account, and its access token identifies only the company. If your app is per-person by nature, a company-scoped app leaves you to track which user owns which install yourself.

You can declare an app as user-scoped when you create it. Klaviyo then handles per-user installs, per-user tokens, and per-user revocation. Store each user's tokens separately, keyed by user (for example, by the sub claim), not by company. If you store one token per tenant_id, each new user's install overwrites the tokens of earlier users.

Choose a scope model

Company-scoped (default)User-scoped
InstalledOnce per accountOnce per user; each user authorizes separately
Token acts asThe companyThe authorizing user
Scopes grantedThe scopes the app requests, independent of the installer's roleOnly the requested scopes the user's role can access
DisconnectRemoves the app for the accountRemoves only that user's install
Installer removed, suspended, or role changedInstall staysInstall is automatically revoked

Build a user-scoped app only if one of the following is true:

  • Your app authenticates each user's own external account (for example, a design tool).
  • Your app acts as an individual and must respect their Klaviyo permissions (for example, agents, MCP clients, or anything that writes on a person's behalf).

Build every other app as company-scoped. Most apps are company-scoped.

📘

Some API endpoints accept only user-scoped tokens and return a 403 for private API keys and company-scoped OAuth apps. Check the reference docs for each endpoint your app calls.

Create a user-scoped app

You choose the scope model once, when you create a new app in the app management page. The default is company-scoped.

🚧

You can't change an app's scope model after creation, and you can't convert an existing app to user-scoped. To build a user-scoped version of an existing app, create a new app.

Keep the following in mind:

  • Private apps can't be user-scoped. Draft apps can.
  • Once published, a user-scoped app can't be unpublished. It can only be deleted.
  • You must provide a rationale (up to 1,000 characters) explaining why your app needs to be user-scoped. During app review, Klaviyo checks your rationale against the criteria in Choose a scope model and may ask you to make your app company-scoped instead.

Declare required and optional scopes

User-scoped apps declare each scope as required or optional. Optional scopes are available only for user-scoped apps.

  • accounts:read is always required and can't be removed. The app management page adds it as a required scope automatically.
  • Required scopes: if the installing user's role doesn't cover a required scope, the install is blocked. Keep this list as short as possible.
  • Optional scopes: the install succeeds even if the user's role doesn't cover an optional scope. Your app must work without it.

For example, an app that acts for each user, such as an agent, can require only accounts:read and declare every other scope as optional. Once the app is allowlisted, it then installs for any role and uses whatever access each user's role allows.

Scope lists must meet these rules:

  • Space-delimited string of valid scope keys.
  • No duplicate scopes.
  • No scope appears in both the required and optional lists.
  • When you update scopes on a user-scoped app, you must also send the optional scopes. Send an empty string if there are none.

To change scopes on a published app, submit a change proposal for Klaviyo to review. You can have one pending proposal at a time. Users must reinstall your app to pick up added scopes. See Update your OAuth scopes.

Read the access token

The access token is an ES256-signed JWT with issuer oauth.services.klaviyo.com and audience a.klaviyo.com. It contains the following claims:

ClaimDescription
subThe authorizing user's ID for user-scoped apps, or the company ID for company-scoped apps.
tenant_idThe company ID, for both scope models. Use this claim, not sub, to identify the company.
subject_typeCOMPANY or COMPANY_USER. Use it to tell the scope model from the token alone.
authorized_byThe ID of the user who consented, for both scope models.
scpArray of granted scopes.

🚧

Granted scopes can be a subset of the scopes you requested. Always read scp to decide which features to enable, rather than assuming your app received every scope it asked for.

Handle the install lifecycle

  • Per-user consent: each user sees the consent screen and authorizes your app separately.
  • Per-user disconnect: when one user disconnects your app, other users' tokens keep working.
  • Repeat installs: if a user installs your app again, Klaviyo returns their existing install.
  • Automatic revocation: if a user is removed from the account, is suspended, or has any role change (not only a downgrade), Klaviyo revokes all of that user's user-scoped installs. Scopes don't shrink in place; the user must reconnect your app.
  • Allowlist removal: if an admin removes your app from the account's allowlist, Klaviyo revokes every existing user install of your app, not only future installs.

When an install is revoked, the user's access token stops working within a few minutes, even if it hasn't expired, and your app's API calls return a 401. An expired access token also returns a 401, so don't treat every 401 as a revocation. First, request a new access token with the user's refresh token. If the refresh request returns a 400 with invalid_grant, check the error code in error_description before you act:

  • 400-02 (revoked) or 400-03 (expired after 90 days of inactivity): prompt the user to reconnect your app.
  • 400-01 (refresh token doesn't exist): check that your app stores the exact refresh token it received, without truncating it. Reconnecting won't fix a storage bug.
  • 400-98 or 400-99 (integration suspended): reconnecting won't help. See error descriptions for suspended integrations.

For every error code, see Troubleshoot OAuth errors.

Understand who can install your app

  • An admin must add your app to the account's allowlist before anyone can install it, whatever their role.
  • Once your app is allowlisted, users with the Manager role or higher, and users with custom roles that include the API keys and integrations permission set, can install it. Users with other roles can install it only if their role covers all of your required scopes.
  • Every user can remove their own installs of user-scoped apps. Removing another user's install requires the User app installations admin permission.
  • If Klaviyo has restricted your app for an account, users in that account can't install it, even if it's allowlisted.

In large accounts, expect adoption in two steps: an admin allowlists your app, then individual users connect it. Users can't request an install from an admin.

Additional resources


Did this page help you?