API keys

An owner or an admin creates a key from Users. The secret is shown once. Copy it then. The list after that shows the prefix, the scope, when it expires, when it was last used, and who created it. Those times are IST. The database stores UTC.

Scopes

The key uses the creator's access, and it cannot exceed that access.

Scope	What it can do
Read-only	Read endpoints only
Read-write	The same actions as the creator
Limited	Only the devices and assets selected on the key

If the creator is read-only, a read-write or limited key stays read-only.

Calling the API

GET /api/devices
X-Api-Key: ac_the_secret_shown_once

A normal login token still works. When a request sends both the token and a key, the token is used.

Revoke on the Users page. The next request with that key is rejected. An expired key is rejected the same way. After revoke, Remove deletes the row from the list. A live key cannot be removed until it is revoked.

Each key allows 120 requests a minute by default. The server setting is API_KEY_RATE_PER_MIN. Every use is an audit row, action API_KEY_USED, with the user who created the key and the path that was called. The secret is not stored and is not written to the audit log.

Create

POST /api/api-keys
{
  "name": "Line 2 reader",
  "scope": "LIMITED",
  "deviceIds": ["device-11111111-1111-1111-1111-111111111111"],
  "expiresAt": "2026-12-31T18:30:00.000Z"
}

POST /api/api-keys/{keyId}/revoke revokes a key. DELETE /api/api-keys/{keyId} removes a revoked key from the list. GET /api/api-keys lists keys and does not return the secret.