Sub-keys

A sub-key is a second credential on the same account, with its own name, its own restrictions and its own rate-limit window — and it can be deleted without touching anything else.

They exist to answer one question: what do you do when something other than you is spending your credits? An agent running unattended, a colleague's client, a deployment you do not watch. Handing each of them the primary key works right up until one of them leaks it, at which point rotating breaks every other connection at once.

What a sub-key is and is not

It is a real credential. It reaches the same catalog, the same way. Nothing about how you call changes; only the value does.

It bills to your account. Sub-keys have no allowance of their own — every call spends the same credits the primary key would. Creating one is a security and operations decision, not a budget one.

It is independently revocable. Deleting a sub-key stops exactly its consumer, immediately, and leaves every other key working. This is the whole point.

It has its own rate-limit window. A sub-key capped at 30 requests a minute has its own bucket, so a bulk job on a sub-key cannot eat the window your interactive traffic is using. Where a sub-key sets its own limit, that limit applies instead of the parent's.

Telling them apart

Sub-keys carry a distinct prefix:

Primary key:  apv_abc123def456…
Sub-key:      apv_sbk_xyz789abc123…

That makes the kind of credential obvious in a config file, a log line or a support ticket without opening the dashboard — useful when you are working out which system a 401 came from, and worth asserting in your own code if a service should only ever hold a sub-key.

Otherwise nothing changes. A sub-key goes in the same config header the primary key would.

Creating one

On the API keys page, under Scoped sub-keys, create a key and give it a name — the field suggests the register to use: Production server, Client X.

Names must be unique on the account, and it is worth spending a moment on them. In six months the name is the only thing telling you whether a key can be deleted. Client X — orders sync answers that; test2 does not.

Then set its restrictions, exactly as you would for the primary key:

• Sources it may not reach
• VerveKit tools it may not use
• An IP allow-list, on Mega
• A per-minute cap below your plan's ceiling, on Mega

Restrictions are per key, so a sub-key can be much narrower than the primary key it lives alongside. Remember that blocking is a deny-list — see key scoping for what that means as the catalog grows.

What they share, and what they do not

The rate-limit row is the one people get wrong. Two keys hammering the API do not politely halve one window; each has its own, which is what makes a rate-capped sub-key an effective way to fence off a bulk job.

What sub-keys cannot do

Two real limits, both better known in advance:

They cannot be rotated. There is no rotate action on a sub-key — you create a replacement and delete the old one, which is the overlap pattern below and is strictly better anyway.

They cannot be nested. A sub-key cannot issue further sub-keys. Every key on the account descends directly from the primary key.

What a sub-key inherits

A sub-key is not a smaller account. It resolves to the same subscription, which decides almost everything about how it behaves:

The plan. Premium fields, response-size ceilings, which VerveKit tools exist — all of it comes from the account's plan, not from the key. A sub-key on a Mega account is a Mega credential.

The credit balance. When the account runs out, every key on it returns 429 at the same moment. A sub-key cannot be given its own budget, which is the one bound people most often expect and do not get. If a consumer must not be able to spend past a point, the lever available is the rate cap, not an allowance.

The suspension state. If the account's key is blocked, sub-keys stop with it.

What a sub-key does not inherit is the primary key's restrictions. Each key's deny-list is its own, so blocking an source on the primary key does not block it on a sub-key issued earlier — worth checking when you tighten scope on an account that already has several keys out.

When to issue one

The rule that holds up: one sub-key per thing that could independently need revoking.

That usually means:

Per environment. Staging and production on separate keys means a leaked staging key — the one that ends up in a screenshot, a CI log or a shared .env — is a five-second fix rather than a rotation of everything.

Per client or per tenant. If you resell or embed access, a key per customer means one customer's compromise is one customer's problem. It also tells you which of them is generating the traffic.

Per job. A nightly enrichment run, a bulk import, a scheduled report. These are the workloads worth rate-capping, and a job that quietly starts retrying in a loop is much easier to stop when it has its own credential.

Per third party. Anything running on a machine you do not administer.

What does not need one: three services inside the same deployment that share a lifecycle and a blast radius. A key per microservice sounds tidy and mostly buys you rotation work.

Revoking

Deleting a sub-key is immediate and final. Its consumer starts getting 401 on the next request, and the editor says so before you confirm: Any app using this sub-key will start receiving 401 responses. This can't be undone.

There is no disable-and-re-enable. If you want a pause rather than an end, block everything the key reaches instead — the credential stays valid and the calls stop with 403.

Rotating without downtime

This is the pattern that makes sub-keys worth adopting before you need them.

Rotating the primary key is instant and has no grace period: the old value stops working the moment the new one exists, so anything still holding it fails until you redeploy. See key rotation.

Sub-keys let you overlap instead:

1. Create a second sub-key for the same consumer, scoped identically.
2. Deploy it. Both keys are live and both work.
3. Confirm traffic has moved — the old key stops appearing in the call log.
4. Delete the old sub-key.

No window where requests fail, and a rollback that costs nothing at any step. For anything you cannot redeploy instantly — a mobile app, a customer's integration, an appliance in a warehouse — this is the only rotation strategy that actually works.

Keeping them honest

Sub-keys accumulate. Three habits keep them from becoming a liability:

Delete on offboarding. When a client leaves, a job is retired or a contractor finishes, the key goes with them. A key nobody remembers issuing is a key nobody will notice being used.

Watch the counter. The sub-key panel shows how many you have against your plan's limit. Hitting it is a prompt to prune rather than to upgrade — most accounts have at least one key from a project that ended.

Check what is actually in use. The primary key's card shows when it was last used; unused credentials are the ones to question first. On Mega, the audit history records sub-key creation and deletion with who did it and when, which is what a compliance review asks for and what you want during an incident.

Next

Key scoping covers the restrictions in detail. Rotation covers replacing a compromised key, and expiration covers making a key retire itself.