API: Getting Started

Availability — The REST API (and API tokens) requires a tier that includes API access — Growth or Business; the Starter tier does not. See Account & Billing.

Knowledge ERP ships a versioned REST API covering every module. This page gets you from zero to your first authenticated request; the full API Reference documents every endpoint.

Base URL and versioning #

All endpoints live under a version prefix:

https://your-domain.com/api/v1

The API version (v1) is independent of the product release version — it changes rarely, and only in ways that respect existing integrations.

Authentication #

The API uses bearer tokens. An administrator creates a token from the API Tokens page in the admin panel; copy it once at creation time. Send it on every request:

curl "https://your-domain.com/api/v1/inventory/units" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

API access requires a plan above the entry tier and an active subscription or trial.

Every token acts as someone #

A token is not an identity of its own — it always acts as a user or a service account, chosen when the token is created. That matters in three ways:

• A token can never do more than its owner can. Whatever modules you grant it, it is still bounded by that person's roles and permissions.
• Removing someone's permission narrows their tokens immediately, with no need to find and reissue anything. Deleting a leaver's user account stops their keys.
• The change history names them. Every write through the API shows who it acted as, and which token was used.

Token scope #

Scope and permissions are two separate limits, and a request has to pass both:

effective permission = the owner's permissions ∩ the token's scope

When creating a token you choose its scope:

• Full access — every module the account subscribes to.
• Limited — pick specific modules and a level per module: read (safe GET requests) or write (also create/update/delete). The list only offers modules included in your subscription.

A request is allowed only when the subscription includes the module, and the token is scoped for it, and the owner holds the matching permission — otherwise you get 403.

Scope only ever narrows. Granting a token sales:write when its owner has no sales permissions is not an error and does not break the token — that part of the scope simply grants nothing, and everything else the token is allowed to do keeps working.

Changing a token's scope later #

A token's module scope can be edited at any time from the API Tokens page. The secret does not change, so an integration that turned out to be over-privileged can be narrowed without coordinating a credential rotation with whoever runs it. The new scope applies from the very next request.

Service accounts #

A service account is a user that exists only to own API tokens. It holds roles and permissions like anyone else, appears in the change history as the actor, and cannot sign in — not to the admin panel, not to the mobile app, not by any other route.

Use one for any long-lived integration, so that:

• the integration does not stop working when the person who set it up leaves;
• the change history shows "Shopify Sync" rather than a former colleague;
• you can grant it exactly the permissions the integration needs and nothing else.

Service accounts do not consume a billing seat. They are capped per plan tier instead:

Tier	Service accounts
Starter	0 (no API access)
Growth	5
Business	15

Creating one needs both the Manage API tokens and Create users permissions. New service accounts start with no permissions at all — grant what the integration needs on the user's own record, then create a token that acts as it.

What a limited token can and cannot do #

A limited token is confined to the modules you picked, at the level you picked:

• Can send GET requests to endpoints in a module it holds at read or write.
• Can create, update and delete in a module it holds at write — write includes read, so you don't need to grant both.
• Cannot touch any other module, at any level. A token holding only inventory:write gets 403 on /sales-orders, in either direction.
• Cannot use the account-wide endpoints at all, read or write — those are /webhooks, /webhook-deliveries, /users, /automation/* (rules, rule logs, approval requests) and /report-definitions. They belong to no single module and can reach across all of them: a webhook forwards any event to any URL, an automation rule acts on any module, and a report definition queries any dataset. No per-module grant can express that, so they require a full-access token.
• Cannot use the mobile endpoints under /v1/mobile. Those are for tokens the mobile app issues at sign-in, which are always full access. The only exceptions are /v1/mobile/me and /v1/mobile/logout, which concern the calling token itself and work with any token.

Refusals come back as 403 with a message explaining which module and direction were refused, in the same shape as every other API error.

If an integration needs webhooks, automation, reports or the mobile endpoints, give it a full-access token — there is no partial grant for those.

Permission refusals #

A full-access token is still not unlimited. When the scope allows a request but the owner does not hold the matching permission, the refusal is also a 403, with a message naming the permission that was missing — for example "Your user account does not have permission to create inventory items." Grant that permission on the owner's user record (or via a role) and the token can do it; no reissue needed.

The account-wide endpoints (/webhooks, /webhook-deliveries) additionally require the Manage settings permission, since they configure the account rather than any one module.

Module gating #

Endpoints are grouped by module (inventory, sales, purchasing, manufacturing, rentals, appointments, surveys). The customer directory (/customers, /customer-contacts, /customer-segments) is shared — any customer-facing module unlocks it, and a token holding any one of sales, appointments, rentals or inventory at the required level may use it — while sales transactions and the CRM pipeline stay under the Sales module.

Rate limits #

Limits depend on your plan tier (for example, higher tiers allow more requests per minute). When you exceed the limit you'll receive 429 Too Many Requests; back off and retry.

Response conventions #

• IDs are surfaced as *_id (UUIDs).
• Money is always an integer number of cents.
• Enums are returned as their string value.
• Timestamps are ISO 8601.
• List endpoints are paginated — results come back under a data array with pagination metadata; page through with the page query parameter.

Line items #

Document line items (sales-order items, invoice items, loan/rental items, kit components, …) are managed through their own *-items endpoints, and the parent document's totals recompute automatically when you add, change, or remove a line.

Attribution #

Writes made through the API are recorded in the change history, attributed to the user or service account the token acts as, plus the token's name — so you can see both who an integration acted as and which key it used.

Next steps #

• Open the full API Reference to explore endpoints and schemas.
• Browse the module guides in the sidebar; where a feature has an API surface, it links straight to the relevant endpoints.
• Set up Webhooks to receive real-time push notifications instead of polling the API.