Keys and environments

Every request carries a secret key as a bearer token:

curl https://api.scanimart.com/v1/stores \
  -H "Authorization: Bearer sk_live_..."

Keys are secrets. Keep them on your servers — never in a POS terminal's config file that a store employee can open, a browser, or a mobile app. If a key leaks, revoke it in the dashboard, or roll it with no overlap. Scanimart can also revoke a single key if we see it in the wild; when we do, your owner, admins and contact e-mail get an e-mail naming the key.

Two environments

The two never mix: a test key is refused by the live host and a live key by the sandbox host, with an error that tells you which host it belongs to. Webhook endpoints, store connections and request logs are separate per environment too, and the dashboard's Test / Live switch chooses which you are looking at.

Both hosts serve the same API at the same version, 2026-10-01. Every event carries api_version so you can tell which shape you are reading.

Company keys and store keys

A key normally covers every store connected to your company. That suits a cloud POS calling from one backend.

Sandbox simulators require a company-wide test key. A store-scoped key cannot create, advance or reset the company's sandbox data.

If your software runs inside each store — a billing PC per outlet — create a store-scoped key for each store instead (choose One store when creating it). It can only see and act on that store, so a key copied off one shop's PC is useless anywhere else.

Claims, webhook endpoints and delivery retries are refused with 403 key_scope_insufficient before anything happens — nothing is changed, and an Idempotency-Key sent with the refused request is not used up, so you can retry it with a company-wide key:

{
  "error": {
    "code": "key_scope_insufficient",
    "message": "This key is limited to one store. Use a company-wide key to claim connection codes."
  }
}

Webhook endpoints receive events for every store you are connected to, and claiming a code adds a store to your company, so both belong to a company-wide key on your own servers.

So the usual set-up for in-store software is: your server claims the store's code with a company-wide key, then you create a store-scoped key for that store and install it on its PC, in the operating system's protected credential store rather than a file staff can open. A store-scoped key is still a secret: whoever holds it can accept and reject that store's orders, change its stock and prices, and disconnect it. If a store disconnects you, revoke its key.

Rolling a key

Rolling issues a new key and keeps the old one working for an overlap you choose — 24 hours by default, up to 7 days — so you can deploy the new one without downtime. After the overlap the old key stops.

Choose No overlap and the old key stops the moment the new one is issued. That, or revoking, is what to do with a key that has leaked: a leaked key rolled with an overlap keeps working until the overlap ends. Revoking stops a key immediately without issuing a new one.

Who can do what

Your teammates sign in to the dashboard with their own accounts. Roles:

Seeing a webhook signing secret again, or rolling it, asks for your password even when you are signed in.

Everyone can see the Activity page: who changed what, including Scanimart's review decisions, suspensions and the keys Scanimart revoked. The notes Scanimart writes with those decisions are shown there to owners and admins only.

Checking a key

GET /v1/ping returns the company and key you are authenticated as. It is the cheapest call there is — use it in health checks.