Support
Guides
Log in

API keys and scopes

Create an API key in Kentro OS, give it only the scopes it needs, bind it to sales channels, and rotate or disable it safely.

Suggest Edits

An API key is a tenant's credential for a system: a channel connector, a warehouse, a storefront server. Its permission groups decide what it may do, and its sales channels decide where it may write.

Who manages keys

Keys live in Kentro OS under Users > API keys; scopes are grouped into permission groups under Users > Permission groups. Only users in the Admin permission group can list, create or edit keys.

Create a key

  1. Sign in to Kentro OS (https://kentro.app; sandbox https://kentro.cc) as a user in the Admin permission group.
  2. Open Users and select the API keys tab.
  3. Click Generate Key.
  4. Fill in Label with the integration's name (Shopify sync, Acme WMS, shop.example.com server).
  5. Choose Permission groups. The groups decide what the key can do; see Scopes.
  6. Optional: choose Sales channels. Left empty, the key has access to all channels; selecting channels restricts its writes to them.
  7. Leave Linked station empty. Neither the Channel API nor the Store API reads it.
  8. Click Generate. The next dialog shows the key and its secret once: copy both, or click Download JSON for a kentro-api-secret.json file holding key and secret.

❗️

The secret is shown once

Kentro does not keep the secret in readable form and cannot show it again. A lost secret means a new key.

The list shows each key's Label, Key, Permission Groups, creation date and Active toggle. Key is the public identifier, safe to quote to support; the secret never appears in the list.

How the two values travel: the Channel API takes both, as kentro-key and kentro-secret. The Store API header X-API-Key carries the secret alone. See Authentication.

Scopes

A key holds the scopes of its permission groups. The Channel API and the Store API scopes appear as their own sections in Users > Permission groups.

ScopeSectionGrants
adminAdminEverything in the tenant, both APIs included.
channel:readChannel APIGET on every Channel API resource: channels, customers, products, catalog, inventory, orders, fulfillment orders, the fulfillment queue, shipments, invoices, payments, purchase orders, vendors, operations.
channel:writeChannel APIEvery write scope below, plus channel:read.
customers:writeChannel APICreate, update and delete customers.
products:writeChannel APICreate, update and delete products; identifiers, listings, price lists, inventory levels, product import.
orders:writeChannel APICreate, update, cancel and delete orders; stock review decisions; order invoices; order import.
fulfillment:writeChannel APICreate, generate, update, fulfill, reroute, cancel and delete fulfillment orders.
shipments:writeChannel APIRecord, update, cancel and delete shipments; ship from the fulfillment queue.
invoices:writeChannel APICreate, update, cancel and delete invoices.
payments:writeChannel APICreate, update, apply, unapply, cancel, decline and delete payments.
purchase-orders:writeChannel APICreate, update, accept, reject, cancel and delete purchase orders.
storefront:serveStore APIServe a custom storefront for the tenant's published storefront hosts: buyer sign-in, catalog, cart, checkout, orders, account.
pixel:read, pixel:manageKentro PixelRead, or read and change, Pixel properties, keys, destinations, audiences and privacy requests through the Pixel management API.
  • A per-resource write scope does not include reads. A key that writes orders and reads them back needs orders:write and channel:read.
  • Permission groups made before these scopes existed keep working: orders:manage counts as orders:write, invoices:manage as invoices:write, payments:manage as payments:write and fulfillment-orders:manage as fulfillment:write.
  • A missing scope answers 403 with code: forbidden and a message naming the scope on the Channel API, and 403 FORBIDDEN "This API key cannot serve a storefront." on the Store API.

Scopes per integration

IntegrationPermission group holdsBind to channels
Sales channel connectorchannel:write, or channel:read plus the write scopes it usesIts own channel
ERP or accounting syncchannel:read, customers:write, products:write, invoices:write, payments:writeThe channels it writes into, or none when it writes into all of them
Warehouse, WMS or 3PLchannel:read, fulfillment:write, shipments:write, and products:write for stock levelsUsually none: fulfillment orders come from every channel
Retailer EDI connectorchannel:read, purchase-orders:write, plus shipments:write and invoices:write when it records themThe retailer's channel
Reporting or BI exportchannel:readNone: reads are never restricted

A custom storefront's server needs storefront:serve and nothing else. An automation that manages Kentro Pixel needs pixel:read or pixel:manage.

Channel bindings

  • A key bound to channels writes only into those channels. A write naming another channelId answers 403 forbidden with detail code not_bound.
  • Reads are not restricted by the binding.
  • An unbound key writes into any channel of its tenant.
  • A channelId that belongs to another tenant, or does not exist, answers 404 not_found (422 unresolved_reference when it is named inside a body).

Rotate a key

Kentro OS has no rotate button: a rotation is a new key and a switch-over.

  1. Click Generate Key and create a key with the same permission groups and sales channels.
  2. Deploy the new secret to the integration and confirm its requests succeed.
  3. Turn off the old key's Active toggle (Disable key).

A bearer token lives 15 minutes, so a process that minted one from the old key needs a token from the new key within that window. Rotate on the schedule your security policy sets, when someone who saw the secret leaves, and at once when a secret may have leaked.

Disable a key

  • Turn off its Active toggle (Disable key). The gateway refuses a disabled key with 401 INVALID_CREDENTIALS.
  • Keys cannot be deleted. A disabled key stays in the list and can be turned back on with the same toggle (Enable key).
  • Edit changes a key's label, permission groups and sales channels. The secret never changes.

Where to store keys

  • In a secrets manager or the hosting platform's encrypted environment variables. Never in source control, a URL, a log line, a browser bundle or a mobile app.
  • One key per integration and per environment, so disabling one stops nothing else.
  • Kentro OS shows when a key was created, not when it was last used: keep a record of which system holds which key.

Updated about 12 hours ago

Did this page help you?