Skip to main content

​
Getting an API key

Needlepath is in early access. Keys are issued per organisation, not self-serve: request access through nextmoca.com and a key arrives with your onboarding. Everything below applies to the key you receive. Every request carries one header:
There is no alternative. No query parameter, no cookie, no x-api-key. The legacy x-api-key header was retired at the Bearer cutover and now fails authorization outright.

​
Key format

np_test_ is reserved and is not minted today.

​
Scope: keys belong to the organisation, not to you

An API key is org-scoped. This has two consequences that surprise people at exactly the wrong moment:
That is correct behaviour, not an oversight. Revoking a person must not strand their company’s production traffic. What you should do at offboarding is review the keys that person created and rotate the ones nobody is now accountable for.Keep your own record of which key belongs to which service and who provisioned it — a “keys created by X” view arrives with the dashboard, and until then that mapping lives with you.
Rate limits, quotas and the per-request ceiling apply to the organisation. Mint separate keys per service anyway: it is the only way to attribute usage, and it means revoking one integration does not take down the rest.

​
The secret is shown exactly once

At mint time you see the full key. After that we hold only its hash and a display prefix, so nobody — including us — can recover it. If you lose it, rotate.

​
Rotation is create-then-revoke, never in place

Key operations go through us today. There is no self-serve console for minting, rotating or revoking yet — that arrives with the account dashboard. The sequence below is what we will do on your behalf, and it is what the self-serve flow will do when it lands, so it is worth understanding either way.
1

Create a second key

Both keys are now live. Your per-org key cap has to have room for the extra — see Limits.
2

Deploy the new key

Roll it out everywhere the old one was used. Take as long as you need; there is no window where neither key works.
3

Confirm the old key is idle

Wait until nothing is using it. Your own deploys are the primary evidence; ask us and we can confirm from telemetry, which is per-key. A per-key last-used timestamp you can read yourself arrives with the dashboard.
4

Revoke the old key

Revocation is not instantaneous on the request path — see below.
Rotating by deleting first is the one sequence that causes an outage, which is why the flow is named this way rather than called “rotate”.

​
Revocation takes up to 60 seconds to bite

Authorization decisions are cached for 60 seconds. A revoked key can therefore still be accepted for up to a minute after you revoke it. This is a deliberate trade: the same cache is what keeps authorization off the request path, and a 60-second TTL is already five times tighter than the platform default.
If a key is actively being abused, 60 seconds is too long. Contact support and say so. There is an immediate incident path that stops the key at the gateway rather than waiting for a cache to expire — it is not something you can trigger from an API call, and it is the correct escalation for a live leak.
The same TTL applies to every claim carried on your key — tier, limits, status. A plan change or a suspension is subject to the same window.

​
What never to put in a request

Two fields, for two different reasons.
Never put a credential — or any secret — in request_id.request_id is your correlation key and we log it, deliberately, so that “what happened to my request” is an answerable question. It is bounded to 128 characters from [A-Za-z0-9._:-] and anything outside that is truncated and de-fanged before it is written (the response then carries format_metrics.request_id_sanitized: true), but bounding is not erasure: a legal string under the cap reaches our logs intact. Put an identifier there, and nothing else.
Record content belongs in records[].text, not in metadata.keywords, tags and attributes are structurally bounded and are not metered. They are bounded by the published size cap; values beyond it are outside the contract and may be rejected.They are read, as indexing hints, so short well-chosen values help. They are not content: nothing parked there can be selected, excerpted or returned to you.

​
Errors you will see

The 403 body deliberately does not say which of those it was. An error that distinguishes “no such key” from “suspended organisation” is an oracle for anyone probing keys.

Full error reference

Every status this API returns, what causes it, and whether to retry.