API keys

Who this is for: Owner — requires integration.apikey.manage. Where: Integrations → API Keys

An API key is how a system outside Nerve authenticates to the public API at /api/v1 and to the MCP endpoint at /api/mcp. It is not a login: it belongs to no person, it carries permissions you choose one at a time, and it is bound to one property.

Before you start:

• The Integration Hub must be switched on for the property. If Integrations is not in your menu, see the overview.
• Have somewhere to put the token before you create the key. You get one chance to copy it.

A key after creation: its prefix, its scopes, its state, a Revoke button. What is not here is the token.

Create a key#

1. Select New key.
2. Type a Name that says what the key is for, not who made it — you will read it in an audit log a year from now.
3. Optionally set Expires in days. Leave it blank for a key that never expires.
4. Select each permission the key needs.
5. Select Create key.

Pick permissions, not a role. A key carries what you tick and nothing else.

Pick the narrowest set that works#

There is no "read-only" preset, and that is deliberate — a key for a reporting tool and a key for a channel manager want different reads. Tick the individual permissions. They are the same strings a role is built from, so roles and what each one can do is the reference for what each one opens.

Important

A key can never out-scope the person who created it. Every permission you tick is intersected with your own effective permissions at that property. Anything you do not hold is dropped silently — the key is created, it simply comes back narrower than you asked for. Check the scopes on the key after you create it; that list is the truth, not the boxes you ticked.

If none of the permissions were yours to grant, the key is not created and you get "none of the requested permissions are yours to grant".

Two consequences worth planning around. A key made by an Owner outlives that Owner's role changing — it keeps the permissions it was minted with. And a key made by someone narrower is quietly narrower, which is a good way to hand key creation to a team lead without handing them the whole API.

Copy the token#

The moment the key is created, the token is shown once:

The only time the token exists on a screen. Leaving this panel is irreversible — there is no "show again".

Caution

Leaving this panel destroys the token. Nerve stores only a SHA-256 hash of it; nothing in the product, the database or a support request can recover the original. Losing it costs you a new key and a redeployment of whatever was going to use it — revoke the orphan and start again.

A token looks like this:

nrvk_<16 hex characters>_<48 hex characters>

The two halves do different jobs, and only one of them is a secret:

Half	What it is
prefix — the first block	A public identifier. It is listed beside the key on this screen and it is the actor in the audit log. Safe to quote in a ticket.
secret — the second block	The credential. Shown once, stored only as a hash.

So when you are chasing down what a key did, quote the prefix; you never need the secret to answer that question.

Use a key#

Send the whole token as a bearer credential:

curl -H "Authorization: Bearer nrvk_..." \
  http://localhost:8080/api/v1/reservations

A call outside the key's permissions is refused with the standard envelope:

{
  "error": "You don't have permission to do that.",
  "code": "unauthorized"
}

To try this without writing any code first, use the playground — it mints a short-lived key and runs the calls in the page.

Note

An MCP key needs integration.mcp.connect as well. The tool permissions alone are not enough to open the connection — /api/mcp checks integration.mcp.connect before it looks at anything else. See MCP agents.

Revoke a key#

1. Select Revoke on the key.

It stops working immediately. There is no grace period and no un-revoke.

Tip

Revoke first, investigate second. A revoked key and a wrong token and an expired key all fail the same way — one 401, with nothing to say which — so a key cannot be probed from outside, and revoking early costs you nothing but a redeployment.

Read what a key has been doing#

Every call an API key makes is recorded in the organisation's audit log with the key prefix as the actor, the channel it came in on, and the outcome — including the refusals. Open Settings → Audit Log, or see MCP agents, where the same log is used to answer the same question about an agent.

What's next#

• Webhooks, retries and replay — for when you would rather be told than poll.
• The playground — run a call against a real response before you build anything.