Getting started

The Channel API is 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, the common flows and the migration from the legacy Channel API.

Base URLs

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.

1. Sign in to the Kentro OS portal as a user with the Admin permission group.
2. Open Users and select the API keys tab.
3. Click Create. Give the key a label that names the integration (Shopify sync, Acme WMS).
4. Pick one or more permission groups. The group decides what the key may do; see Scopes. A key for a full channel integration gets a group that holds channel:write. A read-only reporting key gets channel:read.
5. Optional: restrict the key to specific 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.
6. Click Save. The dialog shows the key's key and secret exactly once. Copy both or download the JSON file. 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 with { "error": "INVALID_REQUEST", "message": "Missing API key credentials" }. A key without the scope an endpoint needs answers 403 forbidden 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.