Set up your OAuth flow

Your client ID is used to publicly identify your app, while your client secret is a confidential string used to authenticate your app. Keep your client secret confidential.

Once you create your app, you can only view your client secret once. Make sure to save it upon creating your app. You can always generate a new client secret later, but regenerating the secret will break any existing connections that use the old client secret.

Scopes define what permissions your app has access to. When setting up your app in Klaviyo, specify scopes in a space-separated list. By default, accounts:read will be included as a scope; this scope is required, and you should keep it in your scopes list.

To know which scopes you need to include, check the documentation for each API endpoint your app uses. Each endpoint's documentation lists the required scopes for that endpoint.

Your app will not be approved if you include more scopes than your app actually uses.

You will also need to include this list of scopes as a query parameter in the authorization URL. Ensure the scopes in the authorization URL match those you set up in-app.

After authorizing your app, Klaviyo will send users back to your app's site along with an authorization code. To protect this sensitive information, you must specify your redirect URLs.

Enter your redirect URLs when setting up your app in Klaviyo. Adding URLs here allowlists them so Klaviyo can send users back to these locations.

When redirecting users to the Klaviyo authorization page, include one of the redirect URLs that has been allowlisted here as the redirect_uri query parameter.

PKCE, or Proof Key for Code Exchange, adds an extra level of security and is required for OAuth 2.1 authentication. PKCE consists of a code_challenge and code_verifier. The code_verifier should be a cryptographic random string 43-128 characters long. The code_challenge is the SHA-256 encoded version of the code_verifier.

Include the code_challenge as a query parameter when redirecting to the Klaviyo authorization URL. If the user authorizes your integration, you will pass the code_verifier to the OAuth token endpoint. Klaviyo can then confirm that your code_challenge and code_verifier match.

When a user clicks to install your app, redirect them to the Klaviyo OAuth authorization page: https://www.klaviyo.com/oauth/authorize

Several required query parameters will need to be appended to this URL:

• client_id: client ID from within Klaviyo
• response_type: coderedirect_uri: the URL where Klaviyo should redirect users after authorizing. This must be one of the redirect URLs you added when setting up your app.
• scope: a space-separated list matching the scopes you added to your app in Klaviyo
• state: a unique customer identifier
• code_challenge_method: "S256"
• code_challenge: a cryptographic string used to verify the client

Our guide to setting up OAuth describes these parameters in more detail.

After a user authorizes your app, they will be redirected to the redirect URL you specify along with an authorization code (the code query parameter) and the state parameter you included upon authorization.

The next step is to exchange this authorization code for an access token and a refresh token by making an API call to https://a.klaviyo.com/oauth/token.

Authenticate this server-side API with your encoded client_id and client_secret. The request should have the following headers:

Authorization: basic  Content-Type: application/x-www-form-urlencoded

The request body should include the following parameters:

• grant-type: authorization_code
• code: The code that Klaviyo returned when redirecting the user to your redirect URL
• code_verifier: Your PKCE code_verifier
• redirect_uri: The same redirect_uri you used when redirecting to the authorization URL

If your request is successful, you will receive an access_token and refresh_token.

Use the access_token in the Authorization header in place of an API key when making server-side Klaviyo API requests. This header will look like:

Authorization: Bearer {access_token}

This API call will return an access token, refresh token, and expires_in, which is the time until the access token expires. If your access token expires, use the refresh token in a POST request to the /token endpoint to request a new access token.