API keys

Every request to Whisperr carries an API key. It tells Whisperr which app the data belongs to and what the sender may do. This page says which key to use where, and how to manage keys in the dashboard.

Which key do I use?

Whisperr has two kinds of ingestion key. In the dashboard they are labeled App and Server.

Dashboard label	Prefix	Where it runs
App	wpk_…	Web and mobile apps: Web, React, Next.js in the browser, React Native, Expo, Flutter, Swift
Server	wrk_…	Your backend only: Node.js, Python, PHP / Laravel, .NET

The App key ships inside your app, so anyone can read it. That is expected. It can send events and identify calls, but it cannot change a user’s existing email address, record consent proof, or export or erase a user.

The Server key can do everything the App key can, and the actions above. See Which API key do I use? for the full list, and Contact consent for when each key can opt a contact in.

Never ship the Server key

Do not put a wrk_… key in browser code, a mobile app bundle or a public repository. Anyone who has it can change your users’ email addresses and export or erase your users. Keep it in your backend’s secrets, such as an environment variable.

Create a key

1. In the Whisperr dashboard, open Settings → API keys.
2. Select Create key.
3. Enter a name, and under Runs in pick App or Server.
4. Select Create key.
5. Copy the key. The dashboard says: “Copy it now. You will not see this key again after you close this panel.”

After you close the panel, the list shows only the first characters of the key, its kind, when it was last used and when it was created.

Only workspace owners and admins can create and revoke keys. Other members can see the list.

Do I need a plan to create a key?

No. Keys work on the free tier, before you start a trial. You can create keys, install an SDK and send events right after you sign up. Whisperr does not charge for the events you send. See Pricing and trial for what the trial adds.

Replace a key

The dashboard has no rotate button. To replace a key without losing events:

1. Create a new key of the same kind.
2. Deploy your app or backend with the new key.
3. When the old key no longer shows recent use, revoke it.

A workspace can have more than one active key, so the old and the new key both work until you revoke the old one.

Revoke a key

In Settings → API keys, open the key and press and hold Hold to revoke. Requests with a revoked key fail with 401 invalid_api_key.

When an SDK gets a 401, it stops sending and keeps its queue. Ship the new key before you revoke the old one, or the release that still uses the old key stops sending events. See Delivery, retries, idempotency.

What if a key leaks?

Revoke it right away and create a new one. A leaked App key is a small risk, because the App key is public by design. A leaked Server key is not: revoke it first, then deploy the replacement.

Common questions

Which Whisperr API key goes in my app?

The App key, which starts with wpk_. It ships inside your web or mobile app, so anyone can read it. The Server key, which starts with wrk_, stays on your backend.

Do I need a paid plan or a trial to create a Whisperr API key?

No. Creating, listing and revoking keys works in every billing state, also before your trial starts. Sending events with a key is not billed either.

Can I see a Whisperr API key again after I create it?

No. The dashboard shows the full key once, right after you create it. After that it shows only the first characters. If you lose a key, create a new one and revoke the old one.

How do I rotate a Whisperr API key?

Create a new key of the same kind, deploy it, and then revoke the old key in Settings → API keys. A workspace can have more than one active key, so both work until you revoke the old one.