An API key is what lets one of your tools talk to the Ezus Pay API.
Each key belongs to your agency, carries a set of permissions, and can be revoked at any time.
Only administrators can create and revoke API keys. Other team members can see that the section exists, but not the keys.
Create a key
Go to Settings → Integrations.
In the API Keys block, click New key.
Fill in the form:
Key name: what the key is for, e.g. Accounting sync or Website. You'll thank yourself later when you need to find which key to revoke.
Permissions: tick only what this tool needs (see the table below).
Expiration: 90 days, 180 days, 1 year, or no expiration.
Click Create key.
Copy the key now. It starts with
ezpay_live_and is shown only once. Once you close this window, nobody, including our team, can display it again. If you lose it, create a new one.
Choose the right permissions
A key can only do what its permissions allow. If a tool tries anything else, the API refuses.
Permission | What the key can do |
Bookings (write) | Create bookings and resync them from Ezus |
Payment links (read) | List a booking's payment links, read a link's details, and list your checkout fields |
Payment links (write) | Create payment links |
Transactions (read) | List payments (agency-wide, per booking or per link) and read a payment's details |
Refunds (write) | Refund payments |
Integrations (write) | Used by the Ezus connection. Your own tools don't need it |
Bookings (read) | Reserved for upcoming endpoints. Not needed today |
A few rules of thumb:
A reporting or accounting tool usually only needs Transactions (read).
A CRM that creates payment links needs Bookings (write) and Payment links (write), plus Payment links (read) if it displays existing links.
Refunds (write) moves money out of your account. Only grant it to a tool that really needs to refund, and that you trust with that responsibility.
Permissions can't be changed after creation. To give a tool more (or fewer) permissions, create a new key and revoke the old one.
Check that your key works
Your developer can test the key with a single request:
curl <https://api.ezuspay.app/v1/ping> \ -H "x-api-key: ezpay_live_..."
The answer confirms which agency the key belongs to and lists its permissions. No permission is needed for this test.
Follow your keys
Your keys are listed in the API Keys block, with two tabs: Active and Revoked. For each key you can see:
its name and the first characters of the key, to tell keys apart
its status: Active, Expired or Revoked
when it was last used, which is useful to spot a key nobody uses anymore
its expiration date, if it has one
its permissions
The "Ezus integration" key
If your agency is connected to Ezus, you'll see a key named Ezus integration with a Protected badge. It was created automatically so that Ezus can work with Ezus Pay. It can't be revoked from this screen: removing it would break the connection with Ezus.
Revoke a key
Revoke a key as soon as a tool no longer needs it, or if you think the key may have leaked.
In the Active tab, click the bin icon next to the key.
Confirm with Revoke.
The key stops working immediately, for every tool using it. This can't be undone: the key moves to the Revoked tab for your records.
Replace a key without downtime
To replace a key (an expiring one, or one you want to change permissions on):
Create the new key.
Update your tool with the new key and check it works.
Revoke the old key.
When a key expires
An expired key stops working on its expiry date and shows the Expired status. It can't be extended: create a new key, update your tool, and you're done. Put a reminder in your calendar when you create a key with an expiration date.
Keep your keys safe
One key per tool. If one tool is compromised, you revoke its key without affecting the others.
Never put a key in code that runs in a browser or a mobile app, and never share it by email or chat. Store it on your server, in a secrets manager or environment variable.
Give each key the minimum permissions it needs.
Review your keys from time to time, and revoke those that haven't been used in months.
If a request is refused
Error code | What it means | What to do |
| No key was sent | Send the key in the |
| The key is wrong or incomplete | Check it was copied in full |
| The key was revoked | Create a new key |
| The key has expired | Create a new key |
| The key lacks a permission for this action | Create a key with the right permissions |