API Authentication

IOTMER uses different credentials depending on the client: console and backend access (JWT or workspace API key), factory / device HTTPS (iotmer-auth-code, then device_http_token for device-only routes), and the end-user mobile app (moid JWT). The interactive API reference lists every path and security scheme.

JWT Bearer Token

Obtain a token via login:

POST /auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGci...",
  "refresh_token": "eyJhbGci...",
  "expires_in": 3600
}

Use the access token in subsequent requests:

Authorization: Bearer eyJhbGci...

Refresh a token

POST /auth/refresh
Content-Type: application/json

{ "refresh_token": "eyJhbGci..." }

API Key

For machine-to-machine use (backend services, CI pipelines), use a workspace API key:

X-API-Key: iotmer_ak_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are workspace-scoped. See API Keys for how to create them, including platform vs provision key kinds.

Provision key and iotmer-auth-code

For POST /provision/device (factory or firmware HTTPS provisioning), send a provision API key in the iotmer-auth-code header as the raw key string (no Bearer prefix). Do not send Authorization on that request. The response includes a device_http_token (dht_… prefix) for routes under /devices/auth/* only.

Mobile app identity (moid)

End-user apps that are not logging in with a console user obtain a moid session via POST /moid/session and refresh via POST /moid/refresh. The access token is a JWT with issuer iotmer.moid (not the same as a console user JWT). It is used on /moid/* routes such as GET /moid/devices. The request body for creating a session may omit workspace_id for a global session, or set it to lock the session to one workspace.

Device HTTP token (dht_…)

The device_http_token from provisioning is used only as Authorization: Bearer on paths under /devices/auth/* (for example POST /devices/auth/bind-claim to link the device to the phone using a one-time claim_code). It must not be interchanged with console JWT, API keys, or moid JWT.

Choosing between JWT and API key

	JWT	API Key (platform)
Use case	User-facing apps, short sessions	Backend services, automation
Expiry	Short-lived (refresh required)	Does not expire (revoke manually)
Scope	User's permissions in workspace	Workspace-scoped

Rate limits

See Rate Limits.