API keys
Admin, API and webhooks (/admin/integrations). Needs module.integrations
and the integration.manage permission.
Issuing a key
Section titled “Issuing a key”Create a key, give it a name that says what it is for, and choose its scopes.
The key is shown once. Copy it then. Only a hash is stored, so a leaked database does not hand over working credentials, and neither can we recover a key you lost. Issue a new one instead.
Scopes
Section titled “Scopes”A key’s scopes are permissions, the same set roles use. Each API surface checks the permissions required for its operation.
In the 0.12.0-rc.3 candidate source, a new key can contain only permissions its signed-in creator holds. Omitting scopes selects the creator’s available read-only permissions; an empty effective grant is refused. The creator’s campus restriction is copied into the key and enforced by REST actions and MCP. This is a stored grant, not a live link to the creator’s role: revoke or replace the key when its intended access changes. Campus-restricted keys cannot authorize tenant-wide SCIM provisioning.
Existing keys retain their stored grants. Review and rotate older keys because their original creator’s permission and campus limits cannot be reconstructed. Check deployment status before relying on candidate behavior.
Give a key the narrowest set that does its job. The two questions worth asking:
- Does it need to write at all? Most integrations read. A read-only key cannot surprise you.
- Does it need this whole area? A key that reads devices does not need
client.view.
Where keys are used
Section titled “Where keys are used”| Surface | How |
|---|---|
| The REST API | x-api-key: <key> |
| The MCP server | Authorization: Bearer <key> |
The MCP server and candidate REST action catalogue are worth thinking about when scoping. tools/list returns only
the tools a key’s scopes permit, so two keys see two different catalogues. A
read-only key cannot see, let alone call, a mutating tool.
Revoking
Section titled “Revoking”Revoke a key from the same screen. It stops working immediately.
Revoke rather than delete when you want the key to remain in the list as revoked.
Rotation
Section titled “Rotation”There is no automatic expiry. Rotate on a schedule you set, and definitely when:
- somebody with access to the key leaves,
- the key has been in a script, a config file or a chat message,
- you are not sure where it has been.
Rotating is: issue a new key, update the client, confirm it works, revoke the old one. In that order, so there is no gap.
Treat them like passwords
Section titled “Treat them like passwords”A key is a credential that acts within your tenant with its scopes. It belongs in a secret store, not in a repository, a shared document, or a message.
Auditing
Section titled “Auditing”Operations that write audit entries carry the API key’s identity. Coverage is not complete: key creation, revocation and deletion do not currently write audit entries, and there is no blanket record of every API read or mutation. Use separate keys per integration and retain your client’s operational logs where a complete history is required.
Naming
Section titled “Naming”Name keys after the thing using them, not after the person who created them.
Asset register sync is useful in an audit log. James test is not, especially
after its owner has left and nobody can say whether it is safe to revoke.