Pairing & security

How a device joins your account, the safeguards on pairing codes and device keys, and what to do if one is exposed.

Pairing code: 6 digits, single use
Code lifetime: 10 minutes
Wrong-code limit: 10 per 15 minutes, per IP

Pairing codes

When you add a device, the dashboard creates a 6-digit code. You enter it on the device's own page, and the device redeems it with the API. The code is the only thing that links a device to your account, so it is deliberately short-lived.

Single useMarked as used the moment a device redeems it.

ExpiresAfter 10 minutes. Ask the dashboard for a new one.

Account-boundIt can only add a device to the account that created it.

Guess-limitedAfter 10 wrong codes in 15 minutes from one IP address, the API answers 429. The proxy also limits pairing requests to 10 a minute per IP.

Carries nothing elseNo bin, name or location is attached to the code.

Device keys

Redeeming a code gives the device its own API key, which it sends with every upload to POST /records.

Random32 random bytes, sent as 64 hex characters.

Returned onceSent to the device in the redeem response and never shown again, including to you.

Stored as a hashThe API keeps only a SHA-256 hash, so the key can't be read back from the database.

Revoked on unpairUnpairing a device revokes its key at once. Later uploads get 401.

Pairing step by step

1
Dashboard
Add device. The dashboard shows a code and a 10-minute countdown. POST /pairing/codes
2
Device page
Enter the code. The device sends it with its hardware ID and receives its key. POST /pairing/redeem
3
Dashboard
Check the hardware ID. The dashboard shows which device redeemed the code. Make sure it matches the ID on the device's page. GET /pairing/codes/{code}
4
Dashboard
Confirm. Name the device and choose its bin. Until you do, its uploads are answered with 409. POST /devices/{id}/setup

If the hardware ID in step 3 isn't yours, don't confirm it. Remove the device and create a new code. An unconfirmed device can't add readings to your account.

If a code or key is exposed

What was exposed	What to do
A pairing code nobody has used	Nothing. Let it expire, or create a new one.
A pairing code someone else redeemed	Don't confirm the unknown hardware ID. Remove it and create a new code.
A device key	Unpair the device in the dashboard, then pair it again to get a new key.
Your password	Change it on the account page. Sessions that are already signed in end within 8 hours.

Accounts and sessions

PasswordsHashed with Argon2id. A wrong email and a wrong password get the same 401 response.

Sign-in limit10 requests a minute per IP to /auth/, then 429.

SessionsAn 8-hour token, kept in a signed, HttpOnly cookie that page scripts can't read.

TransportHTTPS only, with HSTS on the website, the dashboard and the API.

OwnershipEvery bin, device, reading and alert query is filtered by owner. Anything you don't own returns 404.

Deleting an accountDeletes your bins, readings and alerts, unpairs your devices and revokes their keys.

What the open data includes

Readings shared through the open data API are anonymised first: no names, emails, bin names, locations finer than country, or device identifiers. The data dictionary lists every field.

Reporting a vulnerability

Email [SECURITY CONTACT EMAIL] with the steps to reproduce it. Please don't disclose it publicly until it has been fixed.