Authentication

All SimpleOTA APIs use bearer tokens in the Authorization header:

Authorization: Bearer <token>

Tokens are never stored or compared in the clear. The raw value is SHA-256 hashed and looked up against a unique index, so there is no secret-to-secret comparison to time. Only the key prefix is retained for display and audit.

Token kinds

Kind	Scope	Where to get one
Personal (PAT)	All your projects	API Tokens in the top navigation.
Project	One project	The Project API tokens card on the project page.
Device	One device	The device's own detail page, reached from the project's Devices card.

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/		✅		✅
GET /api/v1/projects/	✅		✅ (its own project only)
POST /api/v1/projects/	✅
DELETE /api/v1/projects/{id}/	✅
/api/v1/projects/{id}/...	✅		✅ (scoped)

Creating and deleting projects are the PAT-only operations. Everything else under a project is reachable with an api-scope project token.

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: the token is missing, invalid, or its scope does not cover the endpoint. A device-scope token calling the developer API lands here: to that endpoint, no valid credential was presented.
• 403 Forbidden: the credential is accepted, but the endpoint requires a personal token. Creating and deleting projects are the cases, with "this endpoint requires a personal API token".

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.