Skip to content
plugboard.appRequest a demo

Build on it

API keys

Settings, API & webhooks (/admin/integrations). Needs module.integrations and the integration.manage permission.

Every key stops working while API and webhooks is off in Settings, Modules, including a mail gateway’s intake key, and starts again when it is turned back on.

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.

A key’s scopes are permissions, the same set roles use. Each API surface checks the permissions required for its operation.

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.

The list shows only the keys you could have issued yourself: every permission the key carries, and its desks and campuses, must be within yours. Only those can be changed, revoked or deleted. Anyone else’s key reads as not found.

Existing keys retain their stored grants. Review and rotate older keys because their original creator’s permission and campus limits cannot be reconstructed.

Give a key the narrowest set that does its job. Ask two questions:

  1. Does it need to write at all? Most integrations read. A read-only key cannot surprise you.
  2. Does it need this whole area? A key that reads devices does not need client.view.
SurfaceHow
The REST APIx-api-key: <key>
The MCP serverAuthorization: Bearer <key>

Scopes also shape the MCP server and the REST action catalogue. 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.

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.

There is no automatic expiry. Rotate on a schedule you set, and always 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.

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.

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.

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.