API reference

Authentication, tenant scoping, conventions, errors and rate limits.

The control-plane API is what the admin uses, and it is available to you. Every endpoint is scoped to a single workspace and no endpoint can reach across workspaces.

Base URL and authentication

Requests go to https://<your-domain>/api/... with a bearer token issued in Settings → API keys.

curl https://yourstore.tenza.app/api/orders \
  -H "Authorization: Bearer $TENZA_TOKEN" \
  -H "X-Tenant-Slug: yourstore"

Tenant scoping

The workspace is resolved from the token first, then from X-Tenant-Slug or X-Tenant-Id when a token has access to more than one. A request whose token does not grant access to the named workspace is refused — it does not silently fall back to a different one.

Response envelope

Success responses return the resource or a { items, total } collection. Errors always return the same shape, so one handler covers every endpoint:

{
  "error": "This plan allows 2,500 published products.",
  "code": "limit_reached",
  "limit": 2500,
  "current": 2500
}

`code`	Meaning
`unauthenticated`	Missing or invalid token.
`forbidden`	Authenticated, but the role does not permit this action.
`billing_inactive`	Workspace is `past_due` or `cancelled`; writes are blocked.
`limit_reached`	A plan entitlement would be exceeded.
`not_found`	No such resource in this workspace.
`validation_failed`	The request body failed validation; see `fields`.
`rate_limited`	Too many requests; see `Retry-After`.

not_found is returned for a resource that exists in another workspace as well as for one that does not exist at all. The responses are byte-identical on purpose — distinguishing them would leak the existence of other workspaces’ data.

Pagination

Collections take limit (default 50, maximum 200) and cursor. The response carries nextCursor when more results exist. Offsets are not supported, because they skip and duplicate rows when the underlying data changes between pages.

Rate limits

Limits are per token per minute and are returned on every response as X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 always carries Retry-After.

Webhooks

Register endpoints in Settings → Webhooks. Deliveries are signed, retried with backoff, and recorded — including the failures — so a missed event can be found rather than guessed at.

order.created      order.paid        order.shipped
order.cancelled    order.refunded    product.published
product.unpublished  supplier.error   ticket.created

Idempotency

Send Idempotency-Key on any POST that creates something. A repeat of the same key within 24 hours returns the original response instead of creating a second resource — which matters most on exactly the network where you did not see the first reply.

Something wrong or missing on this page? Tell us — documentation corrections are treated as bugs.