Publishable Keys

A publishable key lets your website or app send events directly to Get Butters, without a server in between.

Unlike a regular API key, a publishable key is safe to put in client-side code. Anyone can read it in your page source, but it can only send events and identify users, and only for the one project you assign it to.

Never put your secret key (the one starting with ev_) in a browser or mobile app. If you need to track events from client-side code, use a publishable key instead.

Create a publishable key

1. Go to the API page in your dashboard.
2. Find the Publishable keys card.
3. Choose the project the key should send events to.
4. Optionally, list the allowed origins, one per line, such as https://example.com. Leave this blank to allow any site to use the key.
5. Click New publishable key. Your new key starts with pk_.
6. Copy the key now. Get Butters shows it to you exactly once and cannot show it again.

Along with the key, the dashboard shows a script tag for the JavaScript SDK with the key already filled in. Paste it into your site and you're sending events.

If you lose a publishable key, create a new one and revoke the old one from the key list on the same page.

Send an event with a publishable key

The easiest way is the JavaScript SDK . If you'd rather call the API yourself, use the key as a bearer token, the same way you would with a secret key:

await fetch('https://app.getbutters.com/api/events', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer pk_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    category: 'signup',
    title: 'New signup',
    user_id: 'u_123',
  }),
})

You don't need to include project in the body. A publishable key already knows which project it belongs to, and defaults to it automatically.

A publishable key ignores notify and created_at if you send them. Since anyone can read the key, it isn't trusted to trigger notifications or backdate events.

What a publishable key can't do

A publishable key can send events (POST /api/events) and identify users (POST /api/identify), and nothing else. Identify from a browser is unverified input, so read the trust warning in People and identify before relying on it.

Every other action, like listing projects, creating insights, or exporting data, requires a secret key.

A publishable key also can't send events to a different project than the one it was created for.

Limits

To protect against abuse from a key anyone can see, publishable keys are rate limited to 60 requests per minute, counted per key and per IP address. Visitors behind the same office or school network share that budget.

If you set allowed origins on the key, only requests from those exact origins are accepted. A request from any other site, or with no origin at all, is rejected.

Troubleshooting

"Publishable keys can only send events and identify users"

You're using a publishable key against an endpoint other than sending events or identify. Use your secret key for everything else, and keep it out of client-side code.

"Origin not allowed for this key"

The site making the request isn't on the key's allowed origins list. Add the site's exact origin (like https://example.com, with no trailing path) to the key's allowed origins on the API page, or remove the origin restriction if you want the key to work from anywhere.

"Rate limit exceeded"

The key has been used more than 60 times in a minute from the same IP address. Wait for the number of seconds in the Retry-After header and try again. If this happens often under normal traffic, check that you aren't sending duplicate events per pageview.

"Project not found"

You named a project in the request body that isn't the one this key belongs to. Remove the project field, or use the key created for that project instead.

Related

See the API Reference for the full request and response format, and status codes for every error above.