Skip to main content

​
Getting an API key

Sign up at console.nextmoca.com with Google, GitHub, or email; there is no waitlist. That address opens the sign-in screen, so on a first visit follow its “New here? Create your workspace” link. From the dashboard, open Keys and create one; the full secret is shown exactly once, at creation, so copy it before you navigate away. See the Quickstart for the full walkthrough. Which workspace you land in depends on your email address. A personal address founds a new workspace of your own, with trial credit on it. A corporate address, once verified, joins the existing workspace for that domain if there already is one, rather than founding a second: balance, usage and limits are shared across its members. Only the first five members of a domain workspace bring a welcome credit into that shared balance; anyone joining after that starts with no grant of their own and spends the shared balance. To have starter credit added, email hello@nextmoca.com. Keys are org-scoped, not personal; see below. For enterprise provisioning, or anything self-serve does not cover, email hello@nextmoca.com. Everything below applies to the key you get either way. 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.The dashboard’s Keys page lists only the keys you minted yourself, and you can revoke only those. A colleague’s keys are not visible to you and cannot be revoked by you, so offboarding is not something you can complete from your own Keys page. Have the departing member revoke their keys before they go, or email hello@nextmoca.com to have them revoked.Keep your own record of which key belongs to which service and who provisioned it. That mapping lives with you; nothing in the dashboard reconstructs it.
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

Minting and revoking keys are both self-serve, from the dashboard’s Keys page: revoking a key stops it working within 60 seconds. Rotation is the two of them in the right order; the sequence below is that order and why it matters. For anything you cannot do from the dashboard, contact hello@nextmoca.com.
1

Create a second key

Both keys are now live, so your key cap has to have room for the extra. On a team workspace that cap counts your own keys, and there is an organisation-wide backstop of 32 on top of it; on a personal workspace it counts the whole organisation’s. 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.
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 effect within a short bounded window

Revocation is not instantaneous. A revoked key can still be accepted briefly after you revoke it, within a short bounded window. Design for that: treat revocation as “in effect shortly”, not “in effect now”.
If a key is actively being abused, that window is too long. Contact support and say so. There is an immediate incident path that stops the key outright rather than waiting for the window to pass. It is not something you can trigger from an API call, and it is the correct escalation for a live leak.
The same window applies to every claim carried on your key: tier, limits, status. A plan change or a suspension takes effect on the same terms.

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