Authentication

The API accepts two kinds of credentials in the Authorization header:

Type	Format	Use
API token	Bearer lit_…	Third-party integrations (recommended)
JWT session	Bearer eyJ…	The web application (expires after 8 h)

API tokens

They are created from the web application under API / Integrations (management roles; standard users and installers cannot issue them).

• The full value (lit_ + 48 hex) is only shown once, at creation — store it in a secrets manager. The server only keeps its hash.
• A token inherits its owner’s role and scope at the time of each call: revoking or deactivating the user disables their tokens.
• Device commands are the exception: they need a signed-in session, and API tokens always get 403 commands_forbidden, even when their owner holds the permission (see Device commands).
• Immediate revocation from the same screen.

curl https://api.linter-iot-stg.icent.digital/v1/devices?limit=5 \
  -H "Authorization: Bearer lit_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

User sessions (JWT)

curl -X POST https://api.linter-iot-stg.icent.digital/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@company.com","password":"********"}'

Response: { "token": "eyJ…", "user": { … } }. The token expires after 8 hours.

Two-step verification (2FA)

If the account has two-step verification enabled, the login returns a challenge instead of the token and sends a 6-digit PIN by email:

{ "twoFactorRequired": true, "challengeId": "665f…" }

It is completed with:

curl -X POST https://api.linter-iot-stg.icent.digital/v1/auth/login/verify \
  -H "Content-Type: application/json" \
  -d '{"challengeId":"665f…","code":"482913"}'

The PIN expires after 10 minutes and allows 5 attempts.

Data scope (tenancy)

Every credential carries a scope (ROOT, subsidiary, distributor or client). The API always intersects that scope with each query on the server: it is not possible to see data from another commercial branch, even by tampering with request parameters.