Keys & pairing

Keys

Each till has its own key: fk_live_ followed by 40 characters (fk_test_ in the sandbox). Send it on every request:

Authorization: Bearer fk_live_...

A key belongs to one shop and acts as that till: the shop’s history shows its name on every stamp and payment.
Fidelia stores only a hash of the key. If it is lost, connect the till again.
The shop can disconnect a till at any time (Fidelia → Tills & POS). Its key then answers 401 invalid_key.
Store the key like a password: encrypted on the till, never in logs or receipts.

Pairing (recommended)

The cashier never sees a key. Your software shows a code; the shop owner types it in Fidelia.

Start: no key needed.

curl -X POST https://api.fidelia.se/pos/v1/pairing \
  -H "Content-Type: application/json" \
  -d '{ "device_name": "Till 1", "partner_id": "pt_..." }'

{ "pairing_id": "806a7164-…", "code": "760978", "poll_secret": "fp_...", "expires_at": "…" }

Show the code on the till’s screen: “Open Fidelia → Tills & POS and type 760 978”. The owner sees your device name and your company (from partner_id), picks a name and a location, and connects it.
Poll every 3 seconds with the poll secret:

curl https://api.fidelia.se/pos/v1/pairing/806a7164-… \
  -H "Authorization: Pairing fp_..."

Status	Meaning
`202` `{ "status": "pending" }`	Not entered yet: keep polling.
`200` `{ "status": "approved", "key": "fk_live_...", "shop": { … } }`	Save the key. It is handed out once.
`410 pairing_expired`	The 10 minutes are over: start again.

Then call GET /me with the new key to load the shop’s cards and settings.

Partner id

Your partner_id (pt_ + 24 characters) comes with your sandbox. Send it when pairing: the till and the shop are then linked to your company (referral agreements, support).

Without pairing

A developer setting up a single shop by hand can ask the owner for a key: Fidelia → Tills & POS → API key for a developer. It is shown once.