An API key is the credential another system uses to add contacts and send email in your account without going through the screen. It's how Casa Moura CafΓ©s' online store sends the pedido-confirmado transactional email on every purchase, or adds a new customer to the Store customers list.
Keys live under Settings βΊ Integrations, in the API keys card, and only the Owner creates and revokes them. The reason: a key reaches the contact base with no screen, no login and no expiry. If the tab doesn't show for you, contact support.
Creating a key
Click New key and fill in:
- Name β the system that will use it, such as Online store. It's how you'll know which one to revoke.
- What this key can do β the permissions. Check only the ones the system uses. One permission does not include another: Add and correct contacts does not grant Read contacts.
- Where it can act β shows when the account has sending spaces. See below.
- Default message type β Transactional or Marketing, used when the send doesn't state the type. It decides which consent is required and where the send appears in reports: marketing honours unsubscribes, transactional does not. Both draw on the same quota. Casa Moura's store uses Transactional, because an order confirmation must arrive even for someone who left the news list.
The key is shown only once
On creation, the Key created window shows the full value. Copy it and store it now: it won't be shown again, not even to support. The window doesn't close when you click outside, on purpose β the way out is Done. The system sends the key in the Authorization: Bearer header of each call.
Lost the key? There's no way to recover it: create another and revoke the lost one.
Where the key can act
With sending spaces in the account, the Where it can act field decides the reach:
- None selected β the key acts only on the main account and reaches no space.
- Spaces selected β it acts only in them, without the main account. If you need both, use two keys.
- All current spaces β a shortcut that selects the spaces that exist today. A space created later is not included on its own: you have to edit the key and select it.
For a call to run in a space, the system sends the space identifier in the X-WiseData-Space header β the value shows under Settings βΊ Sending spaces.
Test key
Check Test key for the system's test environment. With it, the send is accepted in full, but no email goes out and no quota is used: the message goes to the Test inbox, where you read the content and simulate what would happen.
It can only have the sending permissions and read access to fields and lists. It doesn't touch contacts: they would be the account's real contacts, and a test would change the real base. In the list, the key shows the Test badge β check the badge before copying a key into the system's configuration, because swapping one for the other makes production stop sending with no visible error.
Platform key
Shows for accounts with sending spaces. It's for a system that serves several customers, each in their own space: it creates spaces through the API and reaches all of them, including those created later. It's the only key with the space permissions, and it cannot be a test key.
It's the account's widest-reaching credential: if it leaks, it reaches the base of every space. Use it only if your system really creates and operates spaces.
The key list
Each key shows its last four characters, its status (Active or Revoked), its badges, permissions, where it acts, last used and who created it. Last used is what tells you whether a key is still in use β a key that was never used was probably forgotten.
Editing
Edit changes name, permissions, reach and type without changing the key's value: the system keeps working, and what changed applies from the next call. Turning test mode on or off in the edit changes behaviour right away β the screen warns you before saving.
Revoking and replacing
Revoke makes the system using the key stop immediately. The key stays in the list, marked as revoked, to record when that happened.
There's no way to change a key's value. To replace one without bringing the system down: create the new one, install it in the system, check its last used and only then revoke the old one. If the key leaked, reverse the order: revoke first.
Good practice
- One key per system, with only that system's permissions. Revoking one doesn't bring down the others.
- The key belongs on a server. Never in a web page, app, browser or public repository.
Where to go next
- Webhooks β the way back: WiseData Mail telling your system what happened to each email.
- Test inbox β where sends from the test key land.
- API metrics β what the integration sent.
- Sending spaces β each space's identifier for the API.
In short: create one key per system with only the permissions it needs, copy the value right away because it won't show again, select spaces when the key needs to act in them, use the test key for testing and, to replace a key, create the new one before revoking the old.