API Keys #

API keys let automated clients authenticate to a workspace without a user signing in. A key is a workspace principal that carries roles, just like a user, so everything it does passes through the same permission model.

Who can manage keys #

Managing API keys requires the Workspace API keys permission, or workspace ownership. API keys themselves can never manage other keys, even if their roles would otherwise allow it.

Creating a key #

Open Settings → API keys → New API key. You choose:

• Name, a label to recognise the key later.
• Roles, one or more workspace roles. The key can only do what these roles allow; a key with no access to a database cannot query it.
• Expiry, Never, or a fixed lifetime up to one year.

The secret is shown once, immediately after creation. Copy it then; it is stored only as a hash and cannot be retrieved again. If it is lost, rotate or revoke the key.

Rotating a key #

Rotating issues a new secret that inherits the old key’s name, roles, and expiry. The old key keeps working for a 24‑hour grace window so a client can switch over without downtime, then stops automatically.

Revoking a key #

Revoking takes effect immediately: the next request made with that key is rejected. Revocation cannot be undone.

Expiry #

A key with no expiry never expires until revoked. When an expiry is set it is capped at one year. An expired key is rejected the same way a revoked one is.

Treat a key’s secret like a password. Scope each key to the minimum roles its task needs, and revoke keys that are no longer used.