API keys

Every executor authenticates with an API key. The setup wizard creates the first one for you; this page is about managing them afterwards.

The keys page

Remote Executors → API Keys lists every key in the project with its label, key ID and prefix, status, expiry and when it was last used.

The API Keys page listing keys with their status, expiry and last used time

Last Used is the most useful column in practice — it tells you whether a key is actually in service before you revoke it.

⚠️

One key per executor. A key binds to the first executor that connects with it, and everything afterwards — which executor a connection belongs to, which rows appear in its execution history — follows that binding. Two hosts sharing a key will collide. If you’re running several executors, create a key for each.

Create a key

Click Create Key

Field	Notes
Label (required)	How the key appears in this list. Name it after the host it’s for.
Environment	dev, staging or prod. Appears in the key’s prefix, so you can tell at a glance which environment a leaked or misplaced key belongs to.
Expiry	No expiry, or Custom with a date.

The Create New API Key form with label, environment and expiry

Copy the key

The key appears once, with the warning “Copy this API key now — it won’t be shown again!”

qRaptor stores only a hash. There is no way to retrieve the value later — if it’s lost, rotate the key and update the executor.

A key created here isn’t tied to an executor until one connects with it. That’s the normal way to add a second executor to an existing project: create a key, then build an install command around it using the variables in Install & connect.

Rotate a key

Rotate on a key’s ⋮ menu issues a replacement and shows it once, the same as creation.

Rotation exists so you can change a credential without an outage. The old key keeps working for a grace period after rotation, which gives you time to update the executor and restart it. Once the executor reconnects with the new key you’re done; the old one stops working when the grace period ends.

The sequence that avoids downtime:

Rotate, and copy the new key.
Update QRAPTOR_API_KEY where the executor runs.
Restart the executor.
Confirm it’s back to Online and Last Used has updated.

💡

If you set QRAPTOR_API_KEY_FILE instead of QRAPTOR_API_KEY, the agent can pick up a new key from that file without a full restart. Worth setting up in advance if you rotate on a schedule.

Revoke a key

Revoke disables a key permanently. The confirmation notes it cannot be undone.

Revoking stops the key authenticating. An executor that is already connected keeps running on its existing connection until it next reconnects — at which point it’s refused, logs KEY_REVOKED, and reports that the key was revoked in Studio. To stop work immediately, stop the agent on your own host as well.

Revoke when a key has leaked, when a host is decommissioned, or when you’ve finished a rotation and want to retire the old credential early.

Expiry

A key with an expiry date stops working at that date. The executor is refused with KEY_EXPIRED and keeps retrying, so it recovers on its own once you supply a new key.

Expiry dates are worth setting for temporary or third-party executors. For a long-lived executor in your own infrastructure, No expiry plus scheduled rotation is usually the easier operational choice.

Common issues

An executor went offline right after you revoked a key — check you revoked the right one. Last Used tells you which keys are live.
You rotated but the executor still shows Online on the old key — expected during the grace period. It switches when it reconnects.
NONCE_REPLAY in the agent’s logs — two executors are sharing one key. Give each its own.
You’ve lost a key and the executor is still running — leave it running, rotate the key, update the command, then restart at a convenient moment.

Monitor executions — see what your executors are actually doing.