Build with Engage

Authentication

Two ways in, for two different callers. Keys are for your servers. Tokens are for people.

API keys — for your systems

Send the key in a header. Not a query parameter: those end up in access logs, browser history and error reports, and a credential in a log file is a credential that leaks quietly.

X-API-Key: engage_sk_...

A key belongs to exactly one workspace. Every request it makes is scoped to that workspace, and it cannot read or write anything in another.

What a key can reach

An allowlist, and short on purpose:

/v1/events      and everything under it
/v1/customers   and everything under it

A valid key sent to any other path is refused with 403 forbidden. Connecting a WhatsApp number, editing workflows, reading conversations and replying to customers are all things a signed-in person does in the dashboard.

The reasoning is worth stating, because the restriction will feel arbitrary the first time you hit it: a key lives in a server, in an environment variable, in a deployment log, in a CI configuration. Compared to a password behind a login it is a low-trust credential, and the surface it reaches should match. A leaked key can tell us an order was created. It cannot read what your customers said.

Rotating a key

Issue the new one first, deploy it, then revoke the old one. Revocation takes effect immediately — there is no grace period, so doing it in the other order means every call fails until the deploy lands.

Keys are stored as SHA-256 hashes, not bcrypt. That is a deliberate choice and not a weaker one for this purpose: bcrypt salts every row, so a hash cannot be looked up, and verifying a key would mean comparing against every key in the system on every request. A key is high-entropy random data rather than a human-chosen password, so the slow hashing that protects passwords buys nothing here.

Access tokens — for people

The dashboard signs in with POST /v1/auth/login and gets a short-lived access token plus a refresh token. Tokens carry the workspace, so switching workspace means refreshing rather than re-authenticating.

Refresh tokens rotate. Each one works exactly once, and using it invalidates it. This matters if you ever build a client of your own against these endpoints: several requests renewing at the same moment will all present the same token, one will succeed, and the rest will be told it is invalid — which is true, and which will sign the user out of a perfectly healthy session. Renew once and have the other callers wait.