Create an API key, pick the base URL, make the first call.
Kentro has two public APIs, and the first decision is which one a project needs.
- The Channel API (
apis.kentro.live/channel/v1) moves a sales channel's data into and out of Kentro: orders, customers, products, inventory, fulfillment, shipments, invoices, payments, purchase orders. It is for integrations (marketplaces, carts, EDI, 3PLs, ERPs). Kentro is the system of record; the caller is a system. - The Store API (
apis.kentro.live/store/v1) is Kentro's storefront infrastructure (buyer sign-in, the catalog with the buyer's prices, cart, quotes, checkout, orders, invoices, account, subscriptions) for a tenant who builds their own storefront UI instead of using the templates in Kentro OS >Storefront. Start at Store API: Getting started.
This page covers the Channel API: the API an integration uses to put a sales channel's documents into Kentro and read them back: customers, products and listings, orders, fulfillment orders, shipments, invoices, payments and purchase orders. One resource per endpoint, JSON in and out, every write idempotent.
This page gets you from zero to a first authenticated call. The pages that follow cover authentication and scopes, the conventions every endpoint shares and the common flows.
Base URLs
| Environment | Base URL | Portal to create keys |
|---|---|---|
| Production | https://apis.kentro.live/channel | https://kentro.app |
| Sandbox (Kentro staging) | https://apis.kentro.dev/channel | https://kentro.cc |
Every endpoint path on this reference is relative to the base URL: POST /v1/orders is POST https://apis.kentro.live/channel/v1/orders. The sandbox runs the same release train one step ahead of production and holds its own tenants and data; a production key does not work there.
1. Create an API key
An API key belongs to one tenant and carries the scopes of the permission groups assigned to it.
- Sign in to the Kentro OS portal as a user with the
Adminpermission group. - Open
Usersand select theAPI keystab. - Click
Generate Keyand fill inLabelwith a name for the integration (Shopify sync,Acme WMS). - Choose
Permission groups. The group decides what the key may do; see Scopes. A key for a full channel integration gets a group that holdschannel:write. A read-only reporting key getschannel:read. - Optional: choose
Sales channels. A key bound to channels may only write documents into those channels; an unbound key may write into any channel of the tenant. - Click
Generate. The next dialog shows the key'skeyandsecretexactly once. Copy both or clickDownload JSON. Kentro stores a hash of the secret and cannot show it again; a lost secret means a new key.
Permission groups live under Users > Permission groups. The Channel API scopes are listed there under the Channel API section. Until a tenant's portal shows that section, the system Admin group works for every endpoint, and the older orders:manage, invoices:manage, payments:manage and fulfillment-orders:manage scopes keep granting the writes they always granted.
2. Authenticate a request
Send the key pair as two headers on every request:
kentro-key: <key>
kentro-secret: <secret>
Or exchange the pair for a short-lived bearer token once and send Authorization: Bearer <accessToken>; see Authentication for the token flow and the refresh.
3. Make the first call
List the tenant's sales channels. The ids this call answers are the channelId values every document carries.
curl -s https://apis.kentro.live/channel/v1/channels \
-H "kentro-key: $KENTRO_KEY" \
-H "kentro-secret: $KENTRO_SECRET"
{
"data": [
{
"id": "64f0aabb-ccdd-1122-3344-000100000000",
"name": "Web store",
"type": "woocommerce",
"isActive": true,
"currency": "USD"
}
],
"nextCursor": null,
"limit": 50
}
A request without credentials answers 401 unauthenticated, and a key without the scope an endpoint needs answers 403 forbidden, both in the error envelope.
4. Write a document
Writes are POST with a JSON body and an Idempotency-Key header. The key is any string of 7 to 50 characters that identifies the request on your side (an order number, a webhook delivery id). A retry with the same key replays the first answer instead of writing twice.
curl -s -X POST https://apis.kentro.live/channel/v1/customers \
-H "kentro-key: $KENTRO_KEY" \
-H "kentro-secret: $KENTRO_SECRET" \
-H "Idempotency-Key: shop-cust-88412-v1" \
-H "Content-Type: application/json" \
-d '{
"channelId": "64f0aabb-ccdd-1122-3344-000100000000",
"externalId": "shop-cust-88412",
"firstName": "Ada",
"lastName": "Lovelace",
"email": "[email protected]",
"onDuplicate": "update"
}'
{
"data": {
"id": "6512aa00-bb11-cc22-dd33-ee4400000000",
"channelId": "64f0aabb-ccdd-1122-3344-000100000000",
"externalId": "shop-cust-88412",
"name": "Ada Lovelace",
"email": "[email protected]",
"isActive": true,
"version": "4418233"
},
"outcome": "created"
}
201 with outcome: created the first time. The same request again, with the same externalId, answers 200 and outcome: updated or unchanged, because onDuplicate: update makes the create an upsert. Every document a write answers carries the same fields a GET answers.
What to read next
- Authentication and scopes: headers, the bearer token flow, what each scope allows, channel bindings.
- Requests and responses: ids, money, dates, pagination, idempotency, errors, rate limits, dry runs and historical imports.
- Common flows: an order from import to payment, with request and response bodies.
- The endpoint reference below this page, generated from the API's own schemas.

