Authentication

Overview

Every request to the DeviceQuest REST API carries an API key in the X-API-Key header. The key identifies your organisation (tenant), so every response contains only your organisation’s data. Each key has one or more scopes that decide which HTTP methods it may use.

In DeviceQuest you need the api_keys:read permission to see API keys and api_keys:write to create or revoke them. The REST API itself does not use your user permissions: it uses the scopes of the key.

GraphQL uses your signed-in session instead of an API key. See GraphQL.

Base URL

DeviceQuest serves the REST API under /api/v1 on the same address you use to open the app:

https://<your DeviceQuest host>/api/v1

The examples in this section use two environment variables:

export DEVICEQUEST_BASE_URL="https://devicequest.example.com"
export DEVICEQUEST_API_KEY="<your 64-character API key>"

Send the API key

Add the key to every request in the X-API-Key header:

curl -H "X-API-Key: $DEVICEQUEST_API_KEY" \
  "$DEVICEQUEST_BASE_URL/api/v1/assets?limit=5"

• Send the key only over HTTPS.
• Don’t put the key in a query string, a URL or client-side browser code.
• The partner routes under /api/v1/partners accept either a partner key in the X-Partner-Key header or a tenant API key with the admin scope in X-API-Key. See Partner API.

API key format

An API key is a 64-character lowercase hexadecimal string (32 random bytes), for example:

9c4f1e2a7b3d5f60a8e1c2b4d6f8091a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3f

• DeviceQuest shows the full key once, when you create it. Copy it then. DeviceQuest stores only a SHA-256 hash and can’t show the key again.
• The first 8 characters are the key’s prefix. The app shows the prefix in key lists so you can tell keys apart.
• DeviceQuest records when each key was last used. The time updates at most every 5 minutes.

Scopes

A scope is a permission attached to the key. The REST API checks the scope from the request’s HTTP method:

How a request is checked:

A few practical examples:

• A reporting or BI integration that only reads assets and vulnerabilities needs read.
• A CI pipeline that starts scans (POST /scans) or queues reports (POST /reports) needs write.
• Cancelling a scan (DELETE /scans/{id}) needs admin.
• A network tool that only identifies devices needs recognition:read. Add read if it also reads assets.

Give each integration its own key with the smallest set of scopes it needs.

401 and 403 responses

DeviceQuest separates “who are you?” from “what may you do?”:

The recognition endpoints follow the same rules: a missing, unknown, revoked or expired key gets 401, and a valid key without recognition:read (or admin) gets 403.

Example:

{
  "error": "forbidden",
  "message": "API key lacks required scope: admin"
}

Key lifecycle

You manage keys in the app, on the Developer page (API keys section) or on Admin › Security › API keys. See Administration → API keys.

1. Create. On the Developer page, click Create key, enter a Name (for example CI/CD Pipeline), select one or more Scopes, and set Expiry in days (default 90) or select No expiry. Click Create key and copy the key that appears. It is shown only once.
2. Use. Store the key in your secret manager and send it in X-API-Key.
3. Rotate. On Admin › Security › API keys, rotating creates a replacement key and revokes the old one in a single step. The new key keeps the old key’s name, scopes and remaining lifetime unless you change them. Update your integration with the new key straight away: the old key stops working immediately.
4. Expire. After its expiry date a key returns 401 Unauthorized.
5. Revoke. Revoke a key as soon as you no longer need it, or if it may have leaked. A revoked key returns 401 Unauthorized from the next request on.

Creating, rotating and revoking keys need the api_keys:write permission. DeviceQuest records each of these actions in the audit log.

Related pages

• REST API reference
• GraphQL
• SDKs
• Webhooks