WhatsApp API keys: authentication, environments and rotation

Authentication on the Joinotify WhatsApp API is a Bearer token: an API key sent in the Authorization header of every request. The full secret appears once, at creation — only the hash is stored on the server. Losing the secret means creating a new key and revoking the old one; there is no recovery.

curl https://api.joinotify.com/messages \
  -H 'Authorization: Bearer sk_live_xxx'

Anatomy of a key

A key has a visible prefix — something like sk_live_AbCdEf — and a full secret you see only once. The prefix is what appears in the dashboard and in logs: it identifies the key without revealing it.

The practical consequence: log the prefix, never the secret. It is enough to know which key did what.

Where to store it

• Environment variable — the acceptable minimum.
• A secrets manager — the right answer, with audited access.
• Never in the repository — not in an example file, not in a comment, not in the Git history.
• Never in the front end — a key in browser JavaScript is a public key.
• Never in an automation blueprint — Make scenarios and n8n workflows get exported and shared.

The question worth asking: if this file became public right now, what could a stranger send on my company’s behalf?

One key per consumer

A single key for everything is convenient until the day you need to revoke. Separate by who uses it:

1. One key for the production application.
2. One for the test environment.
3. One per third-party integration — the automation, the plugin, the import script.
4. One per external partner, where there is one.

That way, revoking the key an agency leaked into a repository does not take the store down. With a single key, any incident becomes a total outage.

Separating environments

Test and production need distinct keys — and, ideally, distinct numbers. Two concrete reasons:

• A test message sent to a real customer is a reputational incident, and it happens.
• The production number’s quality is affected by any bad send, including test sends.

It is also worth enforcing in code: if the key is production and the environment is not, refuse the send before calling the API.

Rotation without downtime

1. Create the new key and store it in the secrets manager.
2. Deploy the application reading the new key.
3. Confirm, through the prefix in the logs, that traffic has migrated.
4. Only then revoke the old one.

The order matters: revoking before deploying breaks sends in the gap. Rotate periodically, and always when somebody with access leaves the team.

If a secret leaks

1. Revoke the key immediately. It is the access, not the alert.
2. Create and deploy a new one.
3. Check what was sent during the exposure window using the compromised prefix.
4. If improper sends went out, assess the impact on the number’s quality.
5. Remove the secret from wherever it leaked — including the Git history, where deleting the file is not enough.

Step 5 is the most forgotten: a committed and later removed secret remains accessible in history.

Beyond the key

• Validate webhook signatures — the key protects what goes out; the signature protects what comes in.
• Restrict who can call your own layer — do not expose an internal endpoint that sends WhatsApp without authentication of its own.
• Log who triggered what — internal auditing is what answers "who sent that message?".

Signature validation is covered in WhatsApp webhooks.

Frequently asked questions

Can I recover a lost key?

No. Only the hash is stored. Create a new one and revoke the old one.

How many keys can I have?

As many as make sense. One per consumer is the design that lets you revoke without taking everything down.

Is an API key the same as a Meta token?

No. The key authenticates you with the provider; Meta’s token is used by them, on their side, and never reaches you.

Do I need to rotate even without a leak?

Periodically, and mandatorily when somebody with access leaves the team.