Authentication

Every request carries one Bearer token. Which kind of token depends on what you are building.

Factory API keys

In the app, go to Settings, then Webhooks and API keys, and create a key. It is shown to you once, as plain text starting sk_live_. Store it somewhere safe: Skuflo only ever keeps a hash of it, so a lost key cannot be recovered, only revoked and replaced.

An API key acts as an admin on your factory. It can read every order, push new ones, manage retailers, and register webhooks. Treat it like a password: never put it in client side code, a mobile app bundle, or a public repository.

A revoked key stops working immediately (DELETE /v1/api-keys/{id}). There is no limit on how many keys a factory can hold, so a key per integration (one for your ERP, one for a script) makes revoking one never affect another.

Scan station tokens

A scan station token is different on purpose: it can only ever record one kind of scan (produce, stock or dispatch), for one physical station, and nothing else. A compromised station token cannot read an order, list retailers, or touch a webhook.

Pairing is a two step handshake, built for a tablet, phone or a piece of hardware you built yourself:

  1. With a factory API key or a staff session, create a ten minute pairing code: POST /v1/stations/pairing-codes. Show it, or its QR form, to whoever is setting up the station.
  2. The device swaps that code for its permanent token: POST /v1/stations/pair, no other auth needed. The token is shown once, starting st_live_: store it on the device.
Shell
# Step 1, with your factory API key
curl -X POST https://api.skuflo.io/v1/stations/pairing-codes \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Loading bay 1", "role": "dispatch" }'

# { "code": "K7Q2M9XR", "qr": "skuflo://pair?code=K7Q2M9XR", "expires_in_seconds": 600 }

# Step 2, from the device itself, no factory key needed
curl -X POST https://api.skuflo.io/v1/stations/pair \
  -H "Content-Type: application/json" \
  -d '{ "code": "K7Q2M9XR" }'

# { "id": "stn_4a1c", "name": "Loading bay 1", "role": "dispatch", "token": "st_live_..." }

See Scanning from your own hardware for what the token can then do.

Sending the header

Every authenticated request needs one header, whichever kind of token you are using:

Shell
Authorization: Bearer sk_live_51H...

A missing or unrecognised token returns 401. A token that is the right shape but for a role that cannot do what you asked returns 403. Both are covered in Errors.

Staff and retailer sessions

The app itself (and the retailer portal) signs staff and retailer users in with a short lived session token, not an API key. Those login endpoints live under /v1/auth and /v1/portal/auth and are not documented here: they are how our own web app signs a person in, not something a third party integration should call. If you are building an integration, a factory API key or a station token is what you want.