In this lesson, you will learn how to protect your customers' data and keep your account secure from unauthorized access and activity.
This lesson focuses on private API keys. Building an integration that many businesses will connect? Use OAuth instead. See Create a public OAuth app.
How do private API keys work in Klaviyo?
A private API key is a credential your server sends with every request in the Authorization: Klaviyo-API-Key {key} header. Keys start with pk_, and you can create multiple keys for different applications.
Scope is set at creation. Choose Read-only, Full, or Custom per endpoint category. Remember that once these are saved, you won't be able to edit the scope later. To make any changes, you will need to create a new key and retire the old one.
The key is shown only once. To protect your account, Klaviyo displays the full private API key value only right after creation. If you lose the key, there is no way to retrieve it. You can clone it (new secret, same name and scope) or create a fresh key.
Your user role determines whether you can create, clone, and delete keys. See Obtain API credentials.
How to protect your private API keys
Click through the tabbed gallery below to learn 3 best practices for keeping your private API keys safe and secure.
Scope your key to the minimum required permissions
When you create a key, choose Custom scope. Select only the endpoint categories your integration actually uses.
Use this process to choose your scopes:
- Name the key after its integration.
- List exactly which objects the integration creates, reads, or updates.
- Check the scopes each endpoint requires in the Klaviyo developer portal.
- Select scopes to match that list and nothing more.
It's easy to default to Full Access during setup. It's also the riskiest choice.
Example scope setup:
- Profiles: Full
- Events: Full
- Lists: Read-only
- Campaigns: No access
Warning: A key created without a deliberate Custom scope defaults to Full Access. Since you can't edit scope after creating a key, you will need to replace that key to reduce the scope.
Store your keys safely
- Copy the key into a secrets manager or password manager the moment you create it.
- Never hardcode a key. Load it from an environment variable or secrets manager.
- Redact the Authorization header in your logs and error monitoring, so the key doesn't leak through them.
- Add a pre-commit secret scanner to catch accidental commits before they're pushed.
- If several people or systems need the key, share it through the vault's access controls. Don't paste the raw value into a message.
Warning: Treat your key like a password. Never put your key in client-side code, a public repository, a screenshot, a support ticket, a chat message, or an unprotected spreadsheet.
How to rotate keys safely
When you need to rotate a private API key, create a new key before deleting the old one. This helps prevent disruptions to your integration.
Follow these steps in order:
- Create a replacement key.
- Add the new key to your secrets manager.
- Update your application to use the new key.
- Test the integration to make sure it works as expected.
- Delete the old key.
Before you start: Cloning a key preserves its existing scopes. If the old key has more permissions than the integration needs, create a new Custom key and select only the required scopes. Your user role determines whether you can create and manage private API keys. See Obtain API credentials.
Common ways your data gets compromised and what to do
Expand the dropdowns below to read through each scenario and learn how it can happen, what's at risk, how to catch it, and what to do next.
A key leaks through code or tooling
Example: Flexie's team hired a contractor that pushed a .env file to a public repository while debugging an integration. The key had Full Access, so the exposure covered the whole account, not just the one endpoint they used.
What to do
Upon learning of this incident:
- The contractor told the account owner right away
- The account owner created a new custom key, updated the integration, then deleted the exposed key
- The contractor removed the file from the repository. Replacing the key is what protects the account, since the file can still be found in the repository's history.
The activity log shows account changes, but it's not a request-level log. It may not show every API call made with the key, so be sure to keep your own application-side logging.
A retired integration's key never gets deleted
Example: 2 years ago, the Flexie team switched to a new loyalty app, but never deleted the old app's key. It was set to Full Access, and a routine audit caught it.
What to do
When the Flexie team learned of this issue, they:
- Replaced over-scoped keys with correctly scoped ones.
- Deleted the key the day they retired its integration.
- Set a monthly reminder to check Settings > API Keys for unfamiliar names or keys with no live integration to ensure this does not happen again.
Shared logins
Example: Flexie hired an agency to handle some of their biggest implementations. The agency used one login across three team members. The agency left on bad terms, so everyone had to reset their password and MFA.
What to do
After the agency left, the Flexie team hired a new agency and:
- Gave everyone their own login with the minimum role
- Removed access the day the engagement ended
- At offboarding, Flexie checked both users and keys
Phishing and account takeover
Example: Flexie's marketing manager clicked a fake "your account will be suspended" email and entered their password on a lookalike page. MFA stopped the attacker from logging in with the password alone.
What to do: After the manager reported the incident, the Flexie IT team:
- Encouraged the marketing manager to change their password, which ends all active sessions
- Reviewed recent account changes
- Checked their keys for any they did not create and rotated them
To set up MFA for your account, see How to set up multi-factor authentication (MFA).