Authentication¶
All SimpleOTA APIs use bearer tokens in the Authorization header:
Token comparison is constant-time. Tokens are stored hashed; only the prefix is logged for audit / debugging.
Token kinds¶
| Kind | Scope | Where to get one |
|---|---|---|
| Personal (PAT) | All your projects | Account → Tokens in the dashboard. |
| Project | One project | Project → Tokens in the dashboard. |
| Device | One device | Devices → (device) → Tokens in the dashboard. |
See Tokens for how to choose between them.
Which APIs accept which?¶
Project tokens carry a scope that restricts which APIs they can reach:
| Endpoint | PAT | Project token (device scope) |
Project token (api scope) |
Device token |
|---|---|---|---|---|
/api/v1/ota/check/ |
✅ | ✅ | ||
/api/v1/ota/status/ |
✅ | ✅ | ||
/api/v1/projects/ |
✅ | |||
/api/v1/projects/{id}/... |
✅ | ✅ (scoped) |
A project token with device scope can only poll OTA endpoints; it
cannot upload firmware, create deployments, or read any developer API
resource. A project token with api scope has the inverse restriction.
Never give api scope to a token you flash into a field device.
If a device token is extracted from hardware, api scope would let an
attacker upload firmware or modify deployments for your project. Use
device scope for anything deployed to hardware; reserve api scope
for CI pipelines and developer tooling that stays off-device.
Device tokens are scoped to the single device they were issued for and cannot be used to register new devices or access the developer API.
Device tokens¶
Device tokens are intended for production fleets where devices have already been registered. Unlike project tokens, a device token cannot auto-register new devices or access the developer API; it is tightly scoped to the single device it was issued for.
See the Device tokens guide for provisioning steps, firmware usage examples, and security properties.
Errors¶
401 Unauthorized: missing/invalid token.403 Forbidden: token is valid but lacks scope for the resource.
These are real HTTP errors (not the hardware-safe 200 + reason
pattern) because they indicate a misconfigured caller, not a
business-state outcome that a fleet should retry through.
Revoking¶
Tokens can be revoked from the same place they were created. Revocation
is instant; there's no caching layer. A revoked token's last_used_at
is preserved so you can audit when it was last used.