Guides

Start here

What Tillstack isQuickstartAuthentication

Getting data in

How data gets inSync API referenceYour payment providerReconciliation

Building on it

Terminal integrationSales, returns, shiftsCatalog and stockInventory ledgerCatalog layout on devicesProduct picturesReportsWebhooksEmail and EngageRunning without our UI

Using the console

Operator portalMerchant guide

Reference

Sandbox, OpenAPI, PostmanErrors and limitsSecurity

Start here

Authentication

Three kinds of caller, three credentials. Pick the one that matches what you are building.

Caller Credential Used for
A person in a screen JWT from POST /v1/auth/login (+ refresh token) The console, or your own UI for staff
Your server API key (tsk_live_… / tsk_test_…) with scopes, and for operator writes an HMAC signature Sync, transactions, provisioning, integrations
A terminal A session token your server mints for it Catalog, sales, returns, shifts

API keys#

Create one as an admin: POST /v1/organizations/{id}/api-keys with a name and the scopes it needs. The response shows the key and a signing secret once. Only a hash of the key is stored; if you lose it, create another. Only a signed-in person can create keys, so a leaked key can never mint more keys.

Send it on every call: X-Api-Key: tsk_live_… (a bearer header works too).

Keys carry scopes, the smallest set of things they may do: sync:write, catalog:read, catalog:write, inventory:read, inventory:write, sales:read, sales:write, shifts:manage, transactions:write, terminals:session, orgs:write, users:write, branches:write, terminals:write, webhooks:write. Test keys (tsk_test_…) only work against sandbox tenants and live keys only against live ones.

Signing writes#

Endpoints an operator's backend calls to change data (sync, imports, transactions, terminal sessions) also need a signature, so a captured request cannot be replayed or altered.

X-Tillstack-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" using your signing secret>
  • Sign the exact bytes you send. Re-serialising the JSON changes the bytes.
  • t must be within five minutes of our clock.
  • An empty body signs "<t>.".

Node

js
import crypto from 'node:crypto'
export function sign(secret, body) {
  const t = Math.floor(Date.now() / 1000)
  const v1 = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex')
  return `t=${t},v1=${v1}`
}

Python

python
import hmac, hashlib, time
def sign(secret: str, body: str) -> str:
    t = int(time.time())
    v1 = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
    return f"t={t},v1={v1}"

C#

csharp
static string Sign(string secret, string body) {
    var t = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var v1 = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{body}"))).ToLowerInvariant();
    return $"t={t},v1={v1}";
}

A missing or wrong signature is 401. A stale timestamp is 401.

Terminal sessions#

A terminal never holds a long-lived secret. Your backend (which holds the API key) asks for a short session:

POST /v1/terminals/{tid}/sessions        (API key with terminals:session, signed)
-> { "accessToken": "…", "expiresAt": "…" }

The token is bound to that terminal, its merchant and its branch, lasts four hours by default (configurable), and carries only these abilities: read the catalog, record sales and returns, open and close shifts. Your app re-requests one when it expires. A terminal that is switched off or marked lost cannot start a session.

People (JWT)#

POST /v1/auth/login    { "email", "password" }  -> { accessToken, refreshToken, ... }
POST /v1/auth/refresh  { "refreshToken" }       -> a new pair; the old refresh token is retired
POST /v1/auth/forgot-password { "email" }       -> always 200; emails a one-hour link if the account exists
POST /v1/auth/reset-password  { "token", "password" }

Send Authorization: Bearer <accessToken>. Access tokens last 30 minutes. Refreshing rotates the refresh token, and presenting an old one again revokes the whole chain (it means a token was stolen or replayed). What a person may do depends on their role (Merchant guide).

Errors#

401 no or bad credential. 403 valid credential, not allowed to do that. 404 also covers "exists but is outside your tenant", on purpose. See errors and limits.