Manage API keys safely

An API key is a bearer credential: whoever holds it acts as the member who created it, within the key's scopes. Treat it like a password.

Create a key

Under API Keys choose Create key:

The key (drums_sk_<12-character prefix>_<secret>) is shown once, in a dialog that closes only with I have stored it. Drums stores the prefix and a SHA-256 hash, never the key. The key list shows the prefix, scopes, creator, creation time, last use (updated at most once a minute), expiry and state (Active, Expired, Revoked).

Choose scopes

Give each key the least it needs. A key's effective scopes are its scopes intersected with its owner's current role, checked on every call: if the owner is demoted, the key loses the scopes the new role does not allow at once; if the owner leaves the workspace, the key stops working.

For an SDK script that only reads (lists tasks, watches desktops), computers:read is enough. A script that creates desktops needs computers:write too. Host metrics need usage:read.

Rotate without downtime

Rotate creates a new key with the same name, owner and scopes and shows it once; the old key keeps working for 1 hour and then expires. Deploy the new key within that hour.

• Only the key's owner can rotate it (admins and owners can revoke other members' keys, not rotate them).
• A revoked or expired key cannot be rotated; create a new one.
• The new key keeps the old key's remaining lifetime (at least one day).
• Rotations and revocations are recorded in the audit log (api_key.rotate, api_key.revoke).

Revoke

Revoke stops the key on its next call: the gateway does not cache valid keys. The key's owner, admins and owners can revoke. Removing a member revokes all of their keys in that workspace.

Keys in CI

• Store the key in your CI system's secret store and expose it only as DRUMS_TOKEN to the job that needs it. Never commit it, never pass it as a command argument (process lists show arguments), and never print it.
• Use one key per pipeline, named after it, with an expiry, so the audit log and the key list say which pipeline did what and a leak has a bounded lifetime.
• The SDK reads DRUMS_URL and DRUMS_TOKEN from the environment:

jobs:
  eval:
    runs-on: ubuntu-latest
    env:
      DRUMS_URL: https://beta.drums.run/gw
      DRUMS_TOKEN: ${{ secrets.DRUMS_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - run: python3 -m venv venv && venv/bin/pip install drums-sdk
      - run: venv/bin/python evaluate.py

• Wrap your script in with drums.connect() as client: so the desktops it created are closed when it ends; a cancelled job (SIGTERM) runs the same cleanup. Desktops of a job that is killed outright are closed by their lifetime and idle timeout.

If a key leaks

1. Revoke it under API Keys (it stops on the next call).
2. Check the Audit log (owners and admins) for actions by that key: creates, deletes, forks, and api_key.denied entries, which record refused calls with a revoked or invalid key at most once a minute per key.
3. Close any computers you do not recognise under Computers.
4. Create a replacement key with the same scopes.

Every gateway error reply carries a request_id (gw_...); include it when you contact your platform operator.