API keys
Manage keys in Dashboard → API keys or through the management API. You need the api_keys.* permissions.
Creating a key
Choose a name, a role and optional restrictions. The secret is displayed once, in the creation response. List and detail views only ever show the masked app key.
Roles
A key carries one workspace role. The key can call only the operations whose permission is in that role. When you change a role's permissions, every key using it is updated within seconds. See roles and permissions.
Service restrictions
Optionally limit a key to specific APIs (for example only qrcode). Requests to other services return 403 forbidden.
Referrer restrictions
For keys used from a browser, list the pages allowed to use the key. Patterns follow this grammar:
scheme://host[:port][path]
| Part | Rules |
|---|---|
| scheme | http or https |
| host | A domain, IPv4 address or localhost. Prefix with *. to allow any subdomain (the bare domain is not included). |
| port | Optional. Omitted means the scheme's default port (443 or 80). * allows any port. |
| path | Optional. Omitted means any path. A trailing * matches a prefix; otherwise the path must match exactly. |
Examples:
| Pattern | Allows | Does not allow |
|---|---|---|
https://webknx.com/* |
https://webknx.com/pricing |
http://webknx.com/, https://evil-webknx.com/ |
https://*.webknx.com/* |
https://app.webknx.com/, https://a.b.webknx.com/ |
https://webknx.com/ |
http://localhost:3000/* |
http://localhost:3000/ |
http://localhost:3001/ |
https://example.com/app/* |
https://example.com/app/settings |
https://example.com/application |
We match the Referer header when present, otherwise the Origin header (as path /). A key with restrictions rejects requests that carry neither. Matching is on normalized URLs, never on substrings.
Referrer restrictions are not authentication. Browsers set these headers honestly, but any other HTTP client can forge them. Treat a browser key as public and give it the narrowest possible role.
Rotation
Rotating issues a new secret and keeps the same app key, role and restrictions.
- Default: the old secret stops working immediately.
- Overlap window: optionally keep the old secret valid for up to 24 hours while you deploy the new one. After the window it is rejected.
Revocation
Revoking a key is permanent and takes effect on the next request, everywhere. Revoked keys cannot be rotated or restored.
Expiry
Keys can have an expiry date. After it the key is rejected exactly as if it were revoked.
Every create, update, rotate and revoke is recorded in the workspace audit log.