Managing API Keys
API credentials are created and managed from the ArzaMed client app by a user with admin permissions on the equipe, not through the external API itself.
Go to Settings → Equipe → Scroll down to API Key in the ArzaMed client app. From there you can generate a key, view its usage against your plan's monthly quota, and change plans. This page walks through each of those actions and what happens behind the scenes.
If you don't see API keys under Settings → Equipe, external API access may not be enabled for your equipe yet. Contact the administrator of your ArzaMed equipe, who can request it from ArzaMed.
Creating a key
Click Genera chiave (Generate key) and fill in:
| Field | Description |
|---|---|
| Name | A label for your own reference (e.g. App mobile produzione). At least 3 characters. |
| Usage plan | The monthly call quota for this key, see Usage & quotas below. |
Generating a key immediately deactivates any other active key for your equipe. An equipe has at most one active key at a time — creating a new one is effectively "rotating" the key, not adding a second one.
Your client_id and client_secret are shown once, immediately after generation. Copy the secret straight away, see Viewing your secret again if you lose it.
A key is valid for one year from the date it's generated, then it is automatically deactivated. On a paid plan the expiry follows the plan's renewal date instead: the key stays valid until the renewal date plus 30 days, and each renewal extends it. Generate a new key before the old one expires to avoid an interruption.
Usage & quotas
Each key is on one of three plans. Go to Settings → Equipe → Scroll down to API Key to see the active plan, the number of calls used, and the monthly limit:
| Plan | Monthly limit | Annual price |
|---|---|---|
FREE | 1,000 | €0 |
GROWTH | 25,000 | €468 / year |
INTEGRATION | 100,000 | €1,380 / year |
The counter resets on a rolling monthly cycle anchored to your equipe's oldest key. Creating or replacing a key does not reset it. Once you exceed your plan's limit, further API calls are rejected with 429 Too Many Requests until the cycle resets, so keep track of how many calls your integration is making.
You'll receive an email alert at 50%, 75%, and 100% of your monthly quota, so there's a warning before you hit the limit.
Changing your plan
Click Cambia piano (Change plan) next to your active key to compare Free, Growth and Integration side by side, then confirm. The change applies to your equipe's currently active key — it does not create a new one, and your client_id/client_secret stay the same.
Moving to a higher tier (including activating a paid plan from Free) takes effect immediately — you'll be asked to complete payment for the pro-rated cost of the remainder of your current annual cycle.
Moving to a lower tier (including back to Free) doesn't take effect immediately — it's scheduled for your next annual renewal instead, and can only be requested in the 15 days before that renewal date.
Your plan renews annually, aligned with your equipe's ArzaMed subscription renewal. You'll get a reminder email as that date approaches.
Viewing your secret again
Since the secret is only displayed once at creation, recovering it later requires re-verifying your identity by email:
- Request a one-time code — it's emailed to the address on your ArzaMed account.
- Enter the code in the Codice OTP field and confirm. If it expired or didn't arrive, use Reinvia OTP (Resend OTP) to get a new one.
OTP requests are rate-limited — repeated requests in a short window are rejected with 429 Too Many Requests. Wait before retrying rather than resending immediately.
Disabling, revoking, or restoring a key
Disabling, revoking, and re-enabling a key are not self-service actions in the client app — they're performed by ArzaMed on request. If a client_secret is compromised, generate a new key straight away: since an equipe can only have one active key, this immediately deactivates the leaked one, and it will start being rejected with 403 Forbidden even though its underlying credentials still exist. Then contact ArzaMed support so the old key can be fully revoked and its credentials deleted.
Once a key is revoked, its underlying credentials are permanently deleted and cannot be restored — any integration using it must switch to a newly generated key. A disabled (but not revoked) key can be re-enabled by ArzaMed on request, which also deactivates whatever key was active at the time, since an equipe can only have one active key.
A disabled or revoked key is rejected at the API layer with 403 Forbidden even if the token itself hasn't expired — see Authentication for the full validation flow.