FAQ

Examples use the public sandbox tokens, so you can run them as they are.

What format is a HW id?

Free-form: 1–64 printable ASCII characters without spaces, e.g. SN-000123. Ids are case-sensitive; percent-encode reserved characters in URLs (/ → %2F). See Devices.

Why is there no customer in most URLs?

Your API token belongs to one customer, so /firmware, /devices and so on always mean your own data. Only the update check, which devices call without a token, names the customer in its path.

How do I get an account?

Contact the service operator. They create your customer (your domain, e.g. example.com) and invite your first owner by email. Owners then invite colleagues from the console's Members page. Anyone can be invited, whatever their email domain. Meanwhile, the sandbox lets you try almost everything, and the API reference can run requests against it from your browser.

Do devices need a token to check for updates?

No. The update check is public and rate-limited. The download links it returns expire after 5 minutes.

I uploaded a build but no device gets it.

New uploads are staged. Either make it a general release (PATCH /firmware/{id} with {"tag_filter_disabled": true}, or upload with ?general_release=true), or tag it and tag the target devices (and make sure the devices append their HW id to the update-check URL). Also check:

• the update check asks for AFI only by default. Is your build EFI/MFI?
• the device's version really is lower (ordering rules);
• fw_name, hw_name and hw_version match exactly.

A device keeps downloading the same build.

It probably reports a truncated version, e.g. 1.4.1 while running 1.4.1-10-g30d0049. Report the full version.

How do I pull a bad release?

PATCH /firmware/{id} with {"status": "withdrawn"}:

curl -s -X PATCH https://fw.unitcircle.ca/firmware/<id> -H "Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjIwMjYtMTAtMDEtYjItaiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2Z3LnVuaXRjaXJjbGUuY2EiLCJzdWIiOiJzdmM6c2FuZGJveCB3cml0ZXIgKHB1YmxpYykiLCJhdWQiOlsidWNsb2dzZXJ2ZXIiXSwiZXhwIjoxODIyNDE0NTE3LCJuYmYiOjE3OTA4Nzg1MTIsImlhdCI6MTc5MDg3ODUxNywianRpIjoiMDFhMGY4YWQtODkxNC03MjcxLWE4MGEtMjI3NzYyYWY5NjliIiwidHlwIjoiYXBpIiwiY3VzdCI6InNhbmRib3guZXhhbXBsZSIsImNpZCI6IjAxYTBmOGExLTEzYWMtN2QzNC05NDEyLTMwYjAwOGFkYzk4NyIsInNjcCI6ImZ3OnJlYWQgbG9nZGF0YTpyZWFkIGRldmljZXM6cmVhZCB0YWdzOnJlYWQgc3RhdHM6cmVhZCBmdzp3cml0ZSBsb2dkYXRhOndyaXRlIGRldmljZXM6d3JpdGUgdGFnczp3cml0ZSJ9.AdKQR9H96-zqRYvWVf7ALksV1UAht2CzSHdomiepLAfuVjFOPiTowNWssFRgmMuu9z7CHTdug1AcY6jWiMW6DA" \
     -H 'Content-Type: application/json' -d '{"status":"withdrawn"}'

It disappears from update checks immediately and outstanding download links stop working. Set "active" to bring it back.

How do I run a beta?

Tag the beta build beta (without general release) and tag the tester devices beta. Testers are offered it; everyone else isn't. When you're happy, turn on general release.

Are hardware ids secret?

No. For now the update check trusts the HW id at the end of the URL, so tag-targeted builds are "not advertised" to other devices rather than protected. Store each device's identity_pubkey now: challenge–response verification will build on it without changing the update-check URL.

Can I re-upload the same file?

Yes. Identical bytes return 200 and change nothing, which makes retries safe. Different bytes under the same name or version return 409: firmware and log files are write-once.

How long are my files and logs kept?

Firmware and log files are kept for good: they are write-once and can't be deleted. Access records (who downloaded what, when) are kept for 100 days; per-file counters for the life of the file.

How do I verify a token offline?

Fetch /.well-known/jwks.json and verify the JWT with alg=EdDSA, aud=uclogserver and iss=https://fw.unitcircle.ca. Revocation is only known to the server, so validate against the API for anything important.

My token stopped working.

It expired or was revoked, or your customer was suspended. The response says token revoked, expired or unknown. Create a new one in the console. If you were removed from the customer, or your role changed, the tokens you created there were revoked too.

Can my web app call the API directly from the browser?

Yes, with a Bearer token, once your app's origin is registered for your customer (ask your administrator). Update checks are allowed from any origin.

Is there a machine-readable API description?

Yes: OpenAPI 3.1 at /openapi.json.

Where is the service's status?

/health for people; /status, /readyz and /health/history for tools.