Keys, scopes and tenants

Access is the part of an integration project that gets decided in five minutes and lived with for five years. This article is the five minutes, done properly.

Three kinds of identity, and they are not interchangeable

The platform distinguishes between people, buyers and machines. Confusing them is the root of most access problems here.

A machine is not a person. It has no manager, no leaving date and no password-reset flow, and it must not borrow the credentials of someone who has all three.

The credential contract

Every call to https://api.revenexx.com/v1 needs two things:

Send one credential, never both. Machine-to-machine integrations — which is almost everything discussed in this area — use the API key. The bearer token is for an application acting on behalf of a signed-in user, and that is Developer Portal territory.

One key per integration, never per person

This is the rule that makes everything else workable.

Per integration means: one key for the ERP order sync, a different one for the nightly BI extract, a third for the warehouse's stock push. Each is named for what it does — erp-order-sync-prod, not key3 and not thomas.

Four things follow, and each one is a bad day avoided:

You can revoke one integration without stopping the others. The BI key leaks in a support-ticket screenshot; you revoke it and reissue it, and orders keep flowing. With one shared key, revoking it stops everything you own at once.

The logs tell you who did what. An unexpected write is attributable to a system. With a shared key, "something wrote 4,000 products at 02:14" is the beginning of an investigation rather than the end of one.

Scopes can be genuinely tight. A key that has to serve five integrations needs the union of five sets of permissions, which is no restriction at all.

Nobody leaves with it. A key named after a person walks out of the building when they do, and either it keeps working — a security problem — or somebody deletes it and an integration dies on a Friday.

Scopes: give it exactly enough

A scope is a permission the key carries. The key can only do what its scopes allow — a key can be more restricted than the account behind it, never less.

Two kinds are offered when you create a key.

Broad platform scopes, one per platform area:

Capability scopes, which are narrower and are what most integrations should actually get — entered as free text in the form resource.action: products.read, orders.update, orders.create, prices.write.

A worked example for a typical ERP connector:

That key cannot publish a product, cannot send an email, cannot touch a customer record and cannot delete anything. If it is stolen, the damage is bounded by that list. If it holds *, the damage is bounded by your imagination.

Tenant binding

A key belongs to exactly one tenant. It cannot reach another, and if the X-Revenexx-Tenant header disagrees with the key's own binding, the call is refused rather than silently reinterpreted.

That has one practical consequence worth planning for: a sandbox needs its own keys. You cannot point a sandbox integration at production by changing a header, which is precisely the point. See The sandbox.

If you run more than one tenant — a second market, a subsidiary, a separate brand — each has its own keys, its own scopes and its own revocation. See The tenant model.

The secret is shown once

When you create a key, the secret is displayed once and never again. It is stored hashed, so nobody — not you, not your integrator, not revenexx support — can retrieve it later. Lose it and the only path is revoke and reissue.

That is a feature, and it changes your handover process: the secret goes straight into wherever the integrator keeps secrets — a secret manager, a CI variable store, the ERP's credential store — and never into an email, a chat message or a ticket.

Rotation and revocation

Rotation is replacing a working key on a schedule, before anything has gone wrong. Once a year is a reasonable baseline, more often for anything with broad scopes. The safe sequence is always the same:

1. Create the new key with the same scopes and a name carrying the date — erp-order-sync-prod-2027-03.
2. Deploy it alongside the old one. Both are live.
3. Watch the new key make calls successfully.
4. Revoke the old key.
5. Confirm nothing broke, then remove the old secret from wherever it was stored.

Revocation is immediate and irreversible. Anything still using the key starts getting 401 Unauthorized at once. Revoke without hesitation when a key appears in a screenshot, a repository, a support ticket or an email — and when an integrator's contract ends.

An access review worth doing twice a year

Open Settings › API Keys and ask four questions about every key:

1. Do we still know what it is for? A key nobody can explain is a key to revoke.
2. Does its scope still match its job? Scopes get widened during troubleshooting and never narrowed afterwards.
3. Is it still being used? A key with no recent activity is either dead or about to surprise somebody.
4. Does anything hold * that should not?

Next

• Create an API key — the ten minutes that turns this into practice.
• The sandbox — where an integrator should be pointed before production.