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 your own production server needs to call the API? A staging environment, a client integration, a contractor's laptop, a nightly job, a mobile build. Handing each of them the primary key works right up until one of them leaks it, at which point rotating means an outage everywhere 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 header on the same endpoints:

curl 'https://api.apiverve.com/v1/weather?city=London' \
  -H 'x-api-key: apv_sbk_your_sub_key_here'

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:

• Endpoints 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

Three real limits, all better known in advance:

They do not work with the connect-style integrations. Zapier, Make and Pabbly link your account before any step runs, and that connection refuses a sub-key with a 401 and Sub-keys cannot be used for integrations. n8n and Power Automate have no such step — they send the key on each call — so a sub-key is accepted there, and is the better credential for a shared instance. See integrations.

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 endpoint 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.