Skip to docs content
Browse documentation
On this page

Identity Verification

Stop anyone who copies your publishable key from identifying as one of your users. Your server signs each user id, and the key only accepts signed ids.

A publishable key lives in your web page, so anyone can copy it. By default that means anyone can call identify with any user id and change that person's properties, or send events that look like they came from them. Identity verification closes that gap: your server signs each user id with a secret only it knows, and the key refuses any user id that isn't signed.

It's off by default. Keys you already have keep working exactly as before until you turn it on.

What you need

  • A publishable key for the project (see Publishable Keys).
  • The JavaScript SDK 0.2.2 or later, or your own code calling the API.
  • A server that knows which user is signed in, so it can sign their id.

Set it up

  1. Open API in the sidebar and find Identity verification.
  2. Next to your project, click Generate secret. Copy the secret (it starts with idsec_). It's shown once.
  3. Store it on your server as an environment variable, for example BUTTERS_IDENTITY_SECRET. Never put it in the page.
  4. On your server, sign the signed-in user's id and send both the id and the signature to the page.
import { createHmac } from 'node:crypto'

const userHash = createHmac('sha256', process.env.BUTTERS_IDENTITY_SECRET)
  .update(String(user.id))
  .digest('hex')
  1. In the page, pass the signature to identify:
butters.identify(user.id, { plan: 'pro' }, { userHash })
  1. Deploy that change first. Then, in the API keys table, click Verify identity next to the publishable key. A verified ids badge appears on the key.

The SDK remembers the signature with the user, so later track() calls and the feedback widget send it too. Calling reset() on logout clears both.

If you turn on Verify identity before your page sends signatures, every event and identify call that includes a user id will be refused until it does.

Test it

  1. Sign in to your app as a test user and load a page that calls identify.
  2. Open the People page for the project. The test user should appear with their properties.
  3. In your browser's developer tools, check the request to /api/identify. It should return 200.

Events without a user id, such as anonymous pageviews, are never affected.

Rotate the secret

If the secret leaks, click Rotate secret next to the project. The new secret is shown once. Every signature made with the old secret stops working right away, so update your server's environment variable as soon as you rotate.

Turn it off

Click Stop verifying next to the key. The key goes back to accepting any user id.

Troubleshooting

"user_hash is required with user_id for this key": the request had a user id but no signature. Make sure you pass { userHash } as the third argument to identify(), and that the page runs SDK 0.2.2 or later.

"user_hash does not match user_id": the signature was made for a different id or with a different secret. Sign exactly the id you pass to identify(). For a numeric id like 42, sign the text "42". If you rotated the secret, check your server has the new one.

"This key requires identity verification, but the project has no identity secret": generate a secret for the project, or turn verification off for the key.

"Generate an identity secret for this project first": shown when you click Verify identity on a project without a secret. Click Generate secret first.

Secret keys used from your own server are never checked, so server-side identify calls keep working whatever this setting says.