One API Key or Many? Structuring vatnode Access

Short answer: use one live key per service and environment, give each a descriptive label, and treat the key list as an inventory you can revoke from one entry at a time. That gives you attribution and clean rotation, but not isolation: every key on an account shares the same permissions, quota and billing.

The Free plan includes one live key and the test key, so you can register and try the layout before you pick a plan.

One key per service, and what that buys you

A vatnode account can hold several live keys (vat_live_…), and the number depends on your plan. Splitting them by service, such as checkout, back office and a nightly job, gives you three things:

• Independent revocation. If one key leaks or a service is retired, you revoke that key and nothing else stops.
• Rotation without downtime. You can create the replacement, deploy it and only then revoke the old key.
• Attribution. Every check in your history records the label of the key that ran it, so a surprising spike in usage points at a service, not just an account.

Keys are sent as a bearer token, as described in authentication:

curl https://api.vatnode.dev/v1/vat/{vatId} \
  -H "Authorization: Bearer vat_live_YOUR_KEY"

Replace {vatId} with a real VAT number. A live key runs a real check, so it rejects the XX test numbers with 400 INVALID_FORMAT, and that uses no quota.

What a key is in vatnode and what’s shared across the account

A live key is a credential plus a label. It is shown in full once, when you create it, and vatnode stores only a hash of it. The dashboard keeps the label, the last four characters, the creation date and a ‘Last used’ date, which is updated on every authenticated request.

Everything else belongs to the account:

So a key is a handle, not a boundary. Anything one live key creates, every other live key on the account can see and change.

What separate keys do not give you

People coming from a team-oriented setup usually assume otherwise:

• There are no scopes or permissions. Every live key can do everything the API allows for the account, including creating, listing and deleting webhooks and monitoring subscriptions, and listing, reading and cancelling any bulk job on the account, even one submitted with a different key.
• There are no per-key quotas, spending caps or rate limits. All live keys draw from the same monthly quota.
• There are no seats, roles, organizations or SSO. An account belongs to one user. Email, social sign-in and passkeys are ways for that user to sign in, not extra seats.
• Keys do not expire, and they are not rotated automatically.
• Labels cannot be renamed after creation.

So separate keys are the right tool for ‘which service did this, and can I switch it off’, and the wrong tool for ‘this contractor may only run checks’. If you need the second, keep every key, the test key included, out of that person’s hands. Let them call your own service, and let that service hold the vatnode key.

A labeling pattern that survives the audit export

A label is set once, at creation, and has to be 1 to 100 characters. It cannot be renamed, and labels are not unique, so nothing stops you from creating two keys called api. Pick the label as if it were permanent, because it lands in every history row and every export.

A pattern that holds up is service-environment:

• checkout-prod
• backoffice-prod
• nightly-reconcile-prod
• checkout-staging

The label travels with the check. When you export your history, each row has a keyLabel column, so ‘which service ran this validation’ is answered by a column rather than by memory. The export itself is covered in exporting VAT check history for audit. If a service moves or gets renamed, create a new key with the new label and revoke the old one. Past checks keep the old label, which is what an audit trail should do.

A worked layout: one key per service and environment

A layout for a small company that validates VAT numbers at checkout, in a back-office tool and in a nightly job might look like this:

The test key (vat_test_…) works differently. There is exactly one per account, created at signup. It runs checks only against the reserved XX fixture numbers, makes no VIES call, uses no quota and writes nothing to your history. Webhooks and subscriptions reject it with 403 TEST_KEY_NOT_ALLOWED, and it does not count against your live key limit. It still authenticates as your account, so it is not a throwaway value. Regenerating it kills the old one immediately, with no overlap. The fixtures are listed in test mode:

curl https://api.vatnode.dev/v1/vat/XX0000001 \
  -H "Authorization: Bearer vat_test_YOUR_KEY"

Treat it like any other credential. A few rules apply to every key, test or live:

• Never put a key in browser or client-side code. Anything shipped to a browser can be read by anyone who opens the page. Call vatnode from your server.
• Load keys from environment variables or a secret manager.
• In CI, store the test key as a masked secret, not in the pipeline file or a shared .env.
• Keep keys out of source control, logs, error trackers and support tickets.

Rotating a key without downtime

With a spare slot, rotation is four steps:

1. Create a new key with a label that makes the generation clear, for example checkout-prod-2.
2. Deploy it to the service.
3. Open the key list and check that the new key shows a recent ‘Last used’ date and the old one has gone quiet.
4. Revoke the old key.

If you are rotating because a key leaked, skip the overlap: revoke it first and accept the short gap.

On the Free plan, which allows one live key, there is no spare slot. Rotation there is revoke-then-create, and requests fail in the short gap between the two. If that matters, time it for a quiet moment. A plan with more than one live key removes the gap.

Once revoked, a key answers 401 INVALID_API_KEY. The dashboard button is labeled ‘Delete’ and the key disappears from the list, but the checks it already ran stay in your history with their keyLabel.

Revoking has one more effect. A bulk job running under that key is stopped and marked cancelled with the error code API_KEY_REVOKED. Positions that were already answered remain readable with another live key on the same account, and positions that never ran are never charged. If you rotate while a large job is in flight, either wait for it to finish or accept a partial result. The submit-and-poll flow is described in bulk VAT validation.

How many keys your plan allows

The limit applies to active live keys, and it differs by plan. See pricing for the current numbers. Creating a key past the limit returns 422 KEY_LIMIT_REACHED. Revoking a key frees its slot straight away, so the limit counts keys that currently work, not keys you ever made. The test key is not counted.

If you hit the limit, you can merge two low-traffic services onto one key, which costs you attribution between those two and nothing else, or move to a plan with more keys.

Create and revoke are logged

Creating or revoking a live key sends a security email to the account address with the key’s label, its last four characters and the IP address the action came from. The same events appear in the security events list in the dashboard. If you get an email for a key you did not create or delete, treat it as unauthorized access to your login and secure the login first. Then revoke any key you do not recognize, regenerate the test key, and check your webhooks and monitoring subscriptions for endpoints you did not add.

Setting it up

Create a labeled key for each service in your dashboard, deploy it, and watch ‘Last used’ confirm it is live. If you do not have an account yet, register: the test key is created at signup.

FAQ

Should I use one API key or several?

Several, one per service and environment, as long as your plan allows it. Separate keys give you independent revocation, rotation without downtime, and a label on every check in your history. They do not give you separate permissions, quotas or billing, because all of that belongs to the account.

Can I limit a key to certain actions or a quota?

No. Every live key can do everything the API allows for the account, and all live keys draw from the same monthly quota. There are no per-key scopes, quotas, caps or rate limits.

How do I know which key made a check?

Each check in your history carries the label of the key that ran it, in the keyLabel column of the history and of the CSV export. The Last used date on each key in the dashboard shows which keys are still active.

What happens to running bulk jobs when I revoke a key?

Jobs submitted with that key stop with the status cancelled and the error code API_KEY_REVOKED. Positions already answered stay readable with another live key on the same account, and positions that were never answered are never charged.