Keys, webhooks, sandbox

Create an API key

Settings › API Keys — name it for the integration, scope it to exactly what it needs, hand the secret over safely, and test it before anyone builds against it.

Ten minutes, done once per integration. The decisions that matter are the name and the scopes; everything else is mechanical.

Before you begin. Know three things: what the integration will actually do (read orders? write stock? both?), which tenant it belongs to, and where the integrator keeps secrets. If the answer to the third is "we'll email it", stop and fix that first. Read Keys, scopes and tenants if you have not.

1. Open the key list

Go to Settings › API Keys.

The page shows every key on the tenant with its Name / Prefix, its Scopes, and when it was Created / Expires. Only the prefix is visible — the secret itself is not stored anywhere you or anyone else can read it.

The card at the top also gives you the Gateway Endpoint, https://api.revenexx.com, with a copy button. That is the value your integrator needs alongside the key; all paths hang under /v1 from there.

2. Create the key

Select Create API key.

3. Name it for the integration

In General Settings, enter a name that identifies the system, not the person:

Good	Bad	Why
`erp-order-sync-prod`	`thomas`	A person's key leaves when they do
`bi-nightly-export`	`key2`	You cannot revoke what you cannot identify
`wms-stock-push`	`test`	"test" survives into production every time
`sandbox-integrator-mueller`	`api`	Names are how you audit

Include the environment in the name if you run a sandbox tenant as well. Two keys called erp-sync in two tenants is a mistake waiting for a deploy.

4. Choose the scopes

Under Scopes & Permissions you have two ways to grant access, and most integrations need both sparingly.

Predefined scopes are broad, one per platform area: *, auth, search, storage, messaging, functions, imports, exports. Tick only what the integration genuinely uses. A nightly price import needs imports. It does not need messaging.

Custom scopes are the narrow ones, and this is where most integrations should live. Enter them in the form resource.action — products.read, orders.update, orders.create, inventories.write — and select Add for each. They collect under Selected scopes, where you can remove any you added by mistake.

Do not tick *. Full access is for an emergency, not for an integration, and a key created with it on a Tuesday afternoon is still holding it three years later. If you genuinely do not yet know what the integration needs, give it the read scopes now and add write scopes when it asks — that conversation takes five minutes and produces a correct key.

Two scope mistakes are worth naming because both are common:

Granting write when read would do. An ERP that pulls orders and never changes them needs orders.read, not orders.update.
Granting the whole area for one action. imports covers every bulk import. If the integration only ever pushes prices, say so in the handover document even where the scope cannot be narrower, so the review in six months has something to check against.

5. Generate, and copy the secret once

Select Generate Key.

The secret appears once, on a screen that says so. There is no way to see it again — keys are stored hashed, so nobody at your company and nobody at revenexx can retrieve it.

Copy it straight into its destination:

Do	Do not
Paste it into the integrator's secret manager or CI secret store	Email it
Paste it into the ERP's own credential store	Put it in a ticket or a chat message
Have the person who will use it present, and paste it once	Write it on a whiteboard during a workshop
Note where you stored it, in your key inventory	Screenshot the reveal screen

Then select Done, back to API keys and confirm the new key appears in the list with the scopes you expect.

6. Test it before anyone builds against it

One call proves the whole chain — the key, the tenant header, the scopes and the network path:

GET /v1/orders?limit=1 HTTP/1.1
Host: api.revenexx.com
X-Revenexx-Tenant: acme-eu
X-Revenexx-Api-Key: rvxk_…

Result	Means
`200` with a JSON envelope	The key works, and the scope covers this read
`401 Unauthorized`	The key is wrong, was mistyped, or has been revoked
`403 Forbidden`	The key is valid but its scope does not cover this — add the scope
`400 Bad Request`	The tenant header is missing or malformed
`404 Not Found`	No such resource on this tenant — the app may not be installed

Do this yourself, from your own machine, before handing anything over. It separates "the key is wrong" from "their code is wrong", and it saves a day of each side blaming the other.

What to check

The key is in the list, with the name and scopes you intended.
The secret is stored in exactly one place, and you know which.
Your key inventory has a new line: key name, integration, owner, date, who to call if it is revoked.
No existing key was widened to make this work.

When it does not work

401 immediately after creation — the secret was truncated on copy. Long values get cut by chat clients and spreadsheet cells. Revoke and reissue.
403 on some calls but not others — a missing capability scope. Add the specific one rather than the wildcard.
Works from your laptop, not from their server — that is a network problem, not a key problem. See Common API problems.

Set up webhooks — the other half of most integrations.
Common API tasks, by job — what to do with the key now it exists.

Edit this page

Keys, webhooks, sandbox

Set up — APIs, Webhooks & Sandbox.

Set up webhooks

Subscribe your system to platform events: picking topics from the catalogue, the headers a delivery carries, and how your integrator verifies the signature so the endpoint does not accept anyone's POST.