API keys

This page is for administrators. An API key lets another system read tags or write values through the REST API without a browser session. Each key has its own role and can be revoked at any time.

What a key is

• A key is a secret that starts with scx_ followed by 43 URL-safe base64 characters, made from 32 random bytes.
• The gateway stores only a SHA-256 hash of it and a prefix (scx_ plus the next 6 characters) to recognize it by in lists. The secret is shown once, when the key is made, and cannot be read again.
• A key carries a role of viewer, operator or engineer. A key is never an administrator: administering the gateway stays with people. The role is checked when the key is created and again on every request, so a hand-edited row cannot grant admin.
• A key may have an expiry of 1 to 3650 days, or none.
• Every use is attributed to the key: in the audit log its writes appear under the principal apikey:<id>, and on the Clients page a connection made with a key shows the key's name.

The API keys page

Open Gateway, then Security, then API keys. The page lists keys with Name (and the prefix), Role, Status, Last used and Expires. Selecting a key opens a panel beside the list. Anyone who is not an administrator sees "Only administrators can manage API keys."

Status	Meaning
Active	Usable
Expired	Its expiry has passed; the gateway refuses it
Revoked	An administrator revoked it; the row stays so the list still shows what it was

Creating a key

1. Click New key.
2. Under Key, enter a Name of up to 80 characters: what will use it, so you can tell keys apart later.
3. Under Access, choose the Role (Viewer, Operator or Engineer) and when it Expires: Never expires, 30 days, 90 days, 1 year, or Another number of days… (1 to 3650).
4. Click Create key.
5. The panel shows the secret once, with Copy key. Copy it now and store it where the program will read it. Closing the panel without copying shows a warning; the secret is gone after that. If it is lost, revoke the key and make a new one.

Using a key

Send the secret on each request as a bearer token:

GET /api/v1/tags HTTP/1.1
Host: app.scadex.io
Authorization: Bearer scx_...

The gateway picks the key over a cookie when the Authorization header starts with Bearer scx_. A missing, revoked, expired or unknown key answers 401 with {"statusCode":401,"code":"UNAUTHORIZED","message":"Unauthorized"}; a route the key's role does not allow answers 403. The Last used time is refreshed at most once a minute, so it can lag a request by up to a minute.

Requests made with a key do not need a trusted origin (AUTH_TRUSTED_ORIGINS applies to cookie sessions, which browsers send cross-site).

Revoking a key

Select the key and click Revoke key under Revoke, then confirm. Anything using the key stops working at once. A revoked key stays in the list and cannot be switched back on.

Limits

• No scoping: a key with the operator role can write to every tag, and an engineer key can change every tag, type and screen. Make a key per system and give it the lowest role that does the job.
• Keys are for the REST API. A /sync socket checks its role through a session, which a key does not have, so a socket opened with a key cannot write and is closed within 30 seconds. Use a signed-in session for live data; the TypeScript SDK does this for browser apps.
• A key cannot be renamed, re-roled or extended: revoke it and create a new one.
• Up to 80 characters of name; no description field.

API

All routes need the admin role. The full reference is in Admin API.

Route	Purpose
GET /api/v1/admin/api-keys	Every key, newest first: id, name, prefix, role, createdAt, expiresAt, lastUsedAt, revokedAt. Never the secret
POST /api/v1/admin/api-keys	Create {name, role, expiresInDays?}. The response carries secret, this once
DELETE /api/v1/admin/api-keys/{id}	Revoke. The row stays with revokedAt set

Creating a key needs a signed-in person: a request made with another API key is refused with 400 "Only a signed-in person can create keys."