An API key is a password for a program. Anyone who has it can do what the key may do, from wherever the key is accepted, until it expires. This page shows how to keep the damage of a leaked key small. How to create keys and call the API is in Authentication.
Keys are managed on API Keys in the Developer part of the menu (Admin; rotating needs the Owner role).
What a key can never do
These limits hold for every key, whatever you tick:
- A key never goes beyond what the member who created it may do now: “It never goes beyond what its owner may do now.” If the member loses a permission, the key loses it too.
- A key never holds owner-only permissions, and never permissions of the identity and access modules (sign-in, accounts, API keys). So a key cannot create or rotate keys or change members.
- A key’s permission works only while its module is on for your organisation.
- A request that carries a key is judged only as that key; a browser cookie on the same request is ignored.
1. Give only the permissions needed
In New API Key, pick Module permissions one module at a time. Each module offers a Read only preset. Typical integrations:
| Integration | Permissions |
|---|---|
| A reporting tool that reads devices and history | Read only on devices and telemetry |
| An ERP that writes limits to devices | Devices read, attributes write |
| A ticket system that acknowledges alarms | Alarms read, acknowledge |
Avoid one key for everything. One key per integration makes it clear what a leak exposes and lets you revoke one integration without stopping the others.
Integration scopes (Read, Write, Admin, SCIM Read, SCIM Write) are for machine endpoints with their own contract, such as SCIM provisioning. “Module permissions above are what most integrations need.”
2. Pin the key to networks
IP allowlist (optional): “One subnet per line, e.g. 10.0.0.0/8 or 203.0.113.7/32.” Calls from anywhere else are refused with the same answer as an unknown key, so an attacker learns nothing.
Your organisation can set a default for keys without their own list: API Key Settings > Tenant Subnet Allowlist.
3. Let it expire
Every key expires: 90 days by default, at most 365 days (“90 days by default, at most a year.”). In API Key Settings:
| Setting | Default | Use |
|---|---|---|
| Maximum Key Lifetime (days) | 0 (the 365-day cap) | Lower it to force shorter lifetimes. It lowers the default too. |
| Require Expiry on Every Key | Off | API calls that create keys must name an expiry date. |
| Max Active Keys | 0 (unlimited) | Caps how many keys can be active at once. |
| Per-Key Rate Limit (requests/minute) | 0 (the platform default: 1,000 a minute) | Default request limit of each key. The screen calls 0 unlimited; the platform applies 1,000 a minute. |
4. Decide who owns the key
A key stops working when the member who created it leaves the organisation, unless it is marked Service key (“Yes: survives its creator”). Mark keys of production integrations as service keys, and keep a note of who is responsible for each.
5. Rotate regularly
Rotate key creates a successor: “Mint a successor key that inherits this key’s scopes and environment. During the grace window both keys keep working so you can cut over without an outage.” Set the Grace window (days); 0 revokes the old key immediately. The Rotation history card links predecessor and successor.
- Rotate and copy the new secret (“Key rotated. Copy the new secret now.”).
- Put the new key into the integration.
- Check Last used and Last used IP on the old key stop changing.
- Let the grace window end, or revoke the old key.
6. Revoke at once when in doubt
- Revoke Key: “Any integrations using this key will immediately stop working. This action cannot be undone.”
- Deactivate stops a key that you may want back; Activate restarts it.
- In an incident an owner can revoke several or all keys together.
7. Watch the keys
| Signal | Where |
|---|---|
| Last used, Last used IP, Total verifications | The key’s page |
| A dormant key suddenly used from a new address | An audit event (api_key.anomaly.detected) |
| Failed verifications | Audit events (api_key.verify.failed) |
| Creation, rotation, deletion, permission changes | The audit log (api_key.created, api_key.rotated, api_key.deleted) |
| Abuse | The AI firewall records incidents about keys. Its actions to throttle or switch off a key are In development. See The AI firewall. |
The key list also shows a banner for old keys created before per-module permissions: open each and give it only the module permissions it needs.
Storing keys
- Keep keys in your integration’s secret store, never in source code, URLs or tickets.
- Use
testkeys for test systems, so they cannot be mistaken for production keys. - If a key leaked, revoke it first, then find out where it was used from in the audit log.