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.
tmust be within five minutes of our clock.- An empty body signs
"<t>.".
Node
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
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#
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.