API keys and webhooks

Open Settings → API & webhooks (requires the permission to manage API keys and webhooks).

Create an API key

1. On the Keys tab press New key.
2. Give it a name that says what it is for (for example: POS system), choose only the scopes it needs, the company if you want to limit it to one, and an expiry date if you like.
3. Copy the key right away. It is shown once; only its fingerprint is kept. Lost it? Revoke it and create another.

Send it with every request:

Authorization: Bearer mz_live_...
X-Company-Id: <company id>

The company id and ready examples are on the Developer guide tab; the full reference is on the Swagger page.

Test mode

Create the test company from the Overview tab and use mz_test_ keys to experiment without touching your data or sending anything to ZATCA.

Webhooks

1. On the Webhooks tab add your system's URL (https).
2. Choose the events: invoice issued, payment received, ZATCA cleared, stock changed…
3. Copy the secret: every delivery is signed with it so you can check it came from us.

When your system does not answer successfully, the delivery is retried automatically with growing gaps; every attempt is in the delivery log, where you can redeliver it.

Security

• Give each system its own key with the fewest scopes possible.
• Revoke a key at once if you think it leaked.
• Never put a key in a mobile app or a public web page.