API keys

Create scoped keys for server-to-server calls and send them with the X-Revenexx-Api-Key header.

An API key authenticates your server to the platform — a sync job, a webhook handler, a scheduled task, a backend that talks to the API on its own, and a storefront server, which keeps calling with its key while a buyer is signed in. The key carries a fixed set of scopes that limit what it can do, and it identifies one tenant. Keys start with rvxk_.

Use a key only on a server. A key is a long-lived secret with standing access; if it reaches a browser or a mobile app, anyone can read it. For a staff member working in a tool you build, sign them in and use their token instead — see Sessions. A buyer on a storefront is different: your server keeps calling with its key and holds the buyer's session itself.

Create a key

You create and manage keys in Cockpit:

In Cockpit, open Settings (the gear at the bottom of the sidebar) and choose API keys under Developer.
Select Create API key.
Give it a name that says where it runs, for example order-sync-prod.
Select the scopes it needs — grant only the ones that job uses.
Generate the key and copy it. The full value is shown once; store it in your secret manager.

The menu and button labels follow the Cockpit help and have not been checked against the live Cockpit interface (as of 2026-10). The same path is on Prerequisites.

Create a separate key per job or service rather than one shared key. When you rotate or revoke one, the others keep working, and a leaked key affects only its own job.

Use a key

Send the key as X-Revenexx-Api-Key, with your tenant slug. With the Web SDK — running server-side — set it on the client:

Node

import { Client } from "@revenexx/sdk";

const client = new Client()
  .setEndpoint("https://api.revenexx.com")
  .setTenant("<TENANT_SLUG>")
  .setApiKeyAuth("rvxk_...");

Or send the headers directly over HTTP:

cURL

curl https://api.revenexx.com/v1/products \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>"

Load the key from an environment variable or a secret manager — never hard-code it in source and never commit it to git.

Scopes

Each key carries scopes that decide which parts of the API it can reach. A call that needs a scope the key doesn't have is rejected with 403 Forbidden. Grant the narrowest set that does the job: a key that only reads orders doesn't need write access to customers.

A key needs at least one scope. Each scope is one of three shapes:

Scope	Allows
A capability key, e.g. `orders.list`	That one operation.
A namespace with `.`, e.g. `orders.` or `greetings.*`	Every operation whose capability key starts with that namespace — typically everything one App exposes, writes included. For a read-only job, name the read operations one by one instead.
`*`	Everything. Fine on a development key; don't use it in production.

The platform's own services have named scopes of their own rather than capability keys, such as search, storage, messaging, and io for imports and exports (the BMEcat import needs io). Reading the event catalog and an App's settings has no documented scope name yet (as of 2026-10), so use a development key with * for those two. Which scope covers which app maps each App to its namespace. A capability key is declared in the App's manifest.capabilities.json; for an App you didn't write, the API Explorer lists the operations your tenant exposes.

If a call fails with 403, check the key's scopes in Cockpit before changing your code — the request reached the platform and was understood; it just wasn't allowed.

Rotate and revoke

Keys don't expire on their own, so rotate them on a schedule and whenever someone who had access leaves:

Create a new key with the same scopes.
Deploy it to the job that uses it.
Revoke the old key once nothing uses it.

If a key leaks, revoke it immediately in Cockpit. Revocation takes effect within seconds, and any later call with that key fails with 401 Unauthorized.

Troubleshooting

401 Unauthorized — the key is missing, mistyped, or revoked. Confirm the header is X-Revenexx-Api-Key (not Authorization) and that the key is still active.
403 Forbidden — the key is valid but lacks a scope the call needs. Add the scope to the key, or use a key that has it.
Wrong or empty results — check X-Revenexx-Tenant is the right slug.

What's next

Sessions — authenticate a signed-in user instead.
What an AI agent can change — why a read-scoped key is the boundary when an agent holds the credential.
Web SDK — the typed client used in the examples above.
PHP SDK — the same client from PHP.

Was this page helpful?