Skip to content
DeviceQuest DeviceQuest DeviceQuest Docs User Documentation

Documentation

API Keys

Create API keys for integrations and scripts, choose their scopes and lifetime, and rotate or revoke them.

Overview

API keys give scripts, CI pipelines and partner systems programmatic access to your tenant through the DeviceQuest REST API. Each key has a name, one or more scopes and an optional expiry date. The secret is shown once, when you create or rotate the key. Use the API Keys page to issue keys, see which ones are unused or about to expire, and rotate or revoke them. Open it from Admin → API Keys (/admin/security/api-keys).

You need api_keys:read to see keys and their audit trail, and api_keys:write to create, rotate and revoke them. If one of your roles requires MFA (see MFA policy), you must be enrolled in MFA to create, rotate or revoke keys.

Integrations send the key in the X-API-Key header of each REST request. See API authentication for request examples.

Screen tour

  1. New API key: opens the creation wizard. The number beside it is the total number of keys.
  2. Posture: counts of Active, Expiring ≤30d and Stale >30d keys, and Failed auth · 14d, the failed authentication attempts in the last 14 days. Click a count to filter the list to that status; click it again to show all keys.
  3. Activity chart: one bar per day for the last 14 days, split into Admin events (created, rotated, revoked) and Failed auth, with a one-line summary.
  4. Search by name or prefix…: filters the list as you type. The count beside it shows how many keys match, for example 3 of 10.
  5. Status filter: All, Active, Expiring, Stale, Expired, Revoked and Rotated, each with its count.
  6. Status of the key. See Statuses.
  7. Rotation tags under the key name and prefix: replacement marks a key created by rotation, rotated marks the key it replaced.
  8. Rotate and Revoke: available on active, stale and expiring keys. Expired, revoked and rotated keys show Inactive.

Each row also shows the key Name and its prefix (the first characters of the secret, for example b4dc7ea1…), Permissions (the number of scopes; hover to see them), Last used (or Never used with the creation time) and Expires (or No expiry). Click a row to open its details. The search and status filter are kept in the page address.

Create an API key

The New API key wizard has three steps: Configure, Review and Secret.

  1. Click New API key.
  2. Enter a Key name and pick the Permissions and Expires values.
  3. Click Review, check the summary and click Create key.
  4. Copy or download the secret, tick the confirmation and click Done.

Configure

  1. Steps: Configure, Review and Secret.
  2. Key name: describes what uses the key, for example CI Pipeline or Partner Ingestion. Up to 120 characters.
  3. Permissions: the scopes the key gets. Click a scope to select or clear it. Scopes that change data are marked W, and selecting one shows This key has write access. Treat it like a password. Hover a scope to see what it allows. See Scopes.
  4. Expires: 30 days, 60 days, 90 days (default), 180 days, 365 days or No expiry.
  5. Review: available once the key has a name and at least one scope. Cancel closes the wizard.

Review

  1. Summary: the Name, Permissions and Expires values (Never for no expiry).
  2. Back: returns to Configure to change something.
  3. Create key: creates the key. It shows Creating… while it works; an error appears above the buttons if creation fails.

Secret

  1. This is the only time this secret will be shown. Copy it now.
  2. The secret. DeviceQuest stores only a hash of it, so nobody can show it again later.
  3. Copy: copies the secret; the button shows Copied.
  4. Download .env: downloads a file such as devicequest-api-key-ci-pipeline.env containing DEVICEQUEST_API_KEY=<secret>.
  5. I have stored this key safely. Once I close this window, the secret will never be shown again.: tick this to unlock Done. Until you tick it, the wizard can’t be closed.
  6. Done: closes the wizard. The new key appears at the top of the list with a notice such as Created “CI Pipeline”. Store the secret before closing.

Scopes

A key can hold these scopes. The API checks them by HTTP method on every request.

ScopeAllows
readRead data through GET and HEAD requests on the REST API.
writeRead data, and create or update records through POST, PUT and PATCH requests. Does not allow DELETE.
adminFull REST API access, including deletion (DELETE) and the device-recognition endpoints.
recognition:readCall the device-recognition endpoints only.

Scopes are enforced by HTTP method: GET and HEAD require read; POST, PUT, and PATCH require write; DELETE requires admin. The admin scope satisfies every scope.

Give each integration the smallest scope it needs, for example read for a reporting script. To change the scopes of an existing key, rotate it and pick new scopes.

Key details

Click a key row to open its details in a side panel. The same details are available as a full page at /admin/security/api-keys/<key ID>, with All API keys to return to the list.

  1. Key name, status and prefix. Click the prefix to copy it.
  2. Rotate key: opens the rotate dialog.
  3. Revoke key: opens the revoke dialog. Both actions appear only on keys you can still rotate or revoke.
  4. Tabs: Overview, Permissions and Audit.
  5. Key ID: the key’s identifier, with a copy button.
  6. Scopes: the scopes the key holds.

Overview tab

Lists the Status, Key prefix, Key ID, Created (with who created it), Last used (or Never), Expires (with expiring soon when 30 days or fewer remain), Updated, Revoked (on revoked keys) and Scopes. Keys that took part in a rotation also show Rotated from with Previous key, or Rotated to with Next key; click them to open the other key.

Permissions tab

Lists each scope of the key with what it allows (see Scopes). A note explains: Scopes are enforced by HTTP method: GET and HEAD require read; POST, PUT, and PATCH require write; DELETE requires admin. The admin scope satisfies every scope. Scopes that change data are highlighted. Scopes can only be changed by rotating the key with new permissions.

Audit tab

Lists what happened to this key, newest first.

  1. Period: 7 days, 30 days (default), 90 days or All time.
  2. Action filter: All, Created, Rotated, Revoked and Auth failed.
  3. Export CSV: downloads the listed events with Timestamp, Action, Actor, IP and Details.
  4. An event: when it happened, the action, the actor (the user’s email, or anonymous client for a failed request with this key) and the IP address. Click Details to see the recorded details and Hide to fold them.

Click Load more to page further back. With no events the tab shows No events recorded for this key yet. and Clear filters.

Rotate a key

Rotate a key when its secret may have leaked, when someone who knew it leaves, or to change its scopes. Rotation creates a new key and immediately revokes the old one.

  1. Click Rotate on the key’s row, or Rotate key in its details.
  2. Optionally enter a New name (optional) and change the Scopes for replacement key.
  3. Click Rotate key.
  4. Copy or download the new secret, tick the confirmation and click Done.

  1. Rotating creates a new key and immediately revokes the old one. Update the services that use the key with the new secret; the old key stops working as soon as the new one exists.
  2. New name (optional): leave it empty to keep the current name.
  3. Scopes for replacement key: starts with the current scopes; select or clear scopes to change them.
  4. Cancel: closes the dialog without rotating.
  5. Rotate key: creates the replacement and shows its one-time secret.

A notice such as Rotated “CI Pipeline”. The previous key is revoked. confirms the rotation. The old key shows the Rotated status and the new one is tagged replacement.

Revoke a key

Revoke a key that is no longer needed or that may be compromised. Revoking can’t be undone.

  1. Click Revoke on the key’s row, or Revoke key in its details.
  2. If the key was used in the last 24 hours, type REVOKE to confirm.
  3. Click Revoke key.

  1. The key you are about to revoke, with its prefix.
  2. Any service using this key will start receiving 401s immediately. This cannot be undone.
  3. Cancel: keeps the key.
  4. Revoke key: revokes it. For a key used in the last 24 hours it stays disabled until you type REVOKE in the field This key was used recently. Type REVOKE to confirm.

A notice such as Revoked “CI Pipeline”. confirms it. The key stays in the list with the Revoked status, so its history remains visible.

Fields

FieldDescriptionRules
Key nameWhat the key is for.Required. Up to 120 characters.
PermissionsThe scopes the key holds.At least one of read, write, admin, recognition:read.
ExpiresWhen the key stops working.30, 60, 90 (default), 180 or 365 days, or No expiry.
New name (optional)Name of the replacement key when rotating.Up to 120 characters. Empty keeps the current name.
Scopes for replacement keyScopes of the replacement key.Starts with the current scopes.

Statuses

StatusMeaningNext possible status
ActiveThe key works and was used in the last 30 days, or was created less than 30 days ago.Stale, Expiring soon, Revoked, Rotated
Expiring soonThe key expires within 30 days. Shown as Expiring in the filter.Expired, Revoked, Rotated
StaleThe key has not been used for more than 30 days (or never, and it is older than 30 days). It still works.Active (when used again), Expiring soon, Revoked, Rotated
ExpiredThe expiry date has passed. The key no longer works.None
RevokedThe key was revoked. It no longer works.None
RotatedThe key was replaced by rotation and revoked. Its details link to the replacement.None

Keyboard shortcuts

KeyAction
nOpen the New API key wizard.
/Focus Search by name or prefix….
rRotate the key whose details are open.
Shift+RRevoke the key whose details are open.
← / →, Home / EndIn the details panel, move between tabs.
EscClose the details panel.

The shortcuts work when no text field has focus.