Authentication

Create a key

Go to Settings, Integrations, API Access in your dashboard and click Create key. Name it after the system that will use it (Shopify sync, Billing server) so you can tell keys apart later. The full key, starting wamafy_live_, is shown once. We only store a hash of it, so it cannot be shown again; if it is lost, create a new one. A workspace can have up to 25 active keys.

Send it with every request

Put it in the Authorization header as a bearer token:

Authorization: Bearer wamafy_live_...

Keep keys on your server. A key in a browser page, a mobile app or a public repository can be copied and used to message your customers in your name. If one leaks, revoke it on the same page; it stops working at once.

Scopes

Choose what a key may do when you create it. Give each integration only what it needs: a system that sends order updates needs messages:send and probably templates:read, nothing else. A call outside the key's scopes is refused with 403 API_SCOPE_MISSING, naming the scope it needed.

Full access grants every scope, including ones added later, but only for what your workspace has: endpoints that come with an add-on answer 403 PLAN_UPGRADE_REQUIRED until the workspace has that add-on, whatever the key allows. Patient data is never part of Full access: the patient scopes of the Clinics & Hospitals add-on are health information and are granted by name only. Full access suits a key you control end to end, not one handed to a third party.

Expiry and allowed addresses

Two optional limits, set when you create the key, make a leaked key much less useful:

• Expires. After the date you choose (30 days, 90 days or a year), the key is refused with 401 API_KEY_EXPIRED. Good for a short project or a contractor. A key without one never expires.
• Only allow calls from. Your server's public IP addresses or ranges, such as 203.0.113.7 or 203.0.113.0/24 (IPv6 works too). A call from anywhere else is refused with 403 API_KEY_IP_NOT_ALLOWED, and the error names the address it came from, which is the one to add if it is yours. Leave it empty to allow any address.

To change either, create a new key with the limits you want, move your systems to it, and revoke the old one.

Unusual use

Every hour Wamafy compares each key's calls with its usual rate over the past week. When the last hour is far above normal (at least 300 calls and ten times its usual hourly rate), the workspace owner gets an email and the key shows a warning in API Access. That is the usual sign of a leaked key. Nothing is blocked automatically: if you did not expect it, revoke the key and create a new one. A key is flagged at most once a day.

When a key is refused