Developer

Overview

The Developer page is where you set up programmatic access to DeviceQuest. It has four sections, listed in the navigation on the page: Keys, Webhooks, Quickstart and REST API.

• API keys let scripts and other systems call the DeviceQuest REST API.
• Webhooks push DeviceQuest events (a new asset, a finished scan, a new vulnerability) to your own HTTPS endpoint as they happen.
• API quickstart and the REST API Reference show working requests you can copy.

You need api_keys:read or webhooks:read to open the page. Creating and revoking keys needs api_keys:write; creating, editing, testing and deleting webhooks needs webhooks:write.

Screen tour

Click to enlarge

API keys

Create an API key

1. In API Keys, click Create key. A form opens inline above the table.
2. Enter a Name that says what uses the key, for example CI/CD Pipeline.
3. Under Scopes, select at least one scope.
4. Set Expiry in days (default 90), or select No expiry.
5. Click Create key.
6. The secret appears with the warning “This is the only time you will see this secret. Copy it now.” Click Copy, store the key in your secret manager, then click Done.

Click to enlarge

If you lose a key’s secret, revoke the key and create a new one.

Key fields

Send the key in the X-API-Key header of every request:

curl --fail-with-body "https://devicequest.example.com/api/v1/assets" \
  --header "Accept: application/json" \
  --header "X-API-Key: $DEVICEQUEST_API_KEY"

Key details and statuses

Click a key’s name to open its side sheet: Prefix (with a copy button), Scopes, Created, Last used, Expires, and Revoke key.

Revoke keys

• One key: click Revoke on its row, or Revoke key in its side sheet. The Revoke API key dialog warns that any integration using the key stops working immediately. Click Revoke key to confirm.
• Several keys: select them with the row checkboxes (or the header checkbox). In the bar that appears, click Revoke selected, then confirm. Click Clear to deselect.

Revoking cannot be undone.

Webhooks

A webhook sends an HTTPS POST to your endpoint each time a subscribed event happens in DeviceQuest. Each delivery is signed with the webhook’s signing secret, so your endpoint can check that it really came from DeviceQuest.

Create a webhook

1. In Webhooks, click Add endpoint.
2. Enter a Name, for example Slack Notifications.
3. Enter the URL of your endpoint. It must start with http:// or https://.
4. Under Event types, select at least one event.
5. Leave Active selected to start deliveries right away.
6. Click Save.
7. The Webhook created dialog shows the signing secret: “Webhook signing secret — shown only once”. Click Copy secret, store it with your endpoint’s configuration, then click Done.

Click to enlarge

Event types

What each delivery contains

Every delivery is a POST with a JSON body and these headers:

To verify a delivery, recompute the signature from the raw body (BODY), the X-DeviceQuest-Timestamp header (TS) and your signing secret (SECRET), and compare it with the X-DeviceQuest-Signature header (RECEIVED):

# BODY must hold the exact bytes you received (including any trailing newline).
EXPECTED=$(printf '%s%s' "$BODY" "$TS" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.*= //')
[ "$EXPECTED" = "$RECEIVED" ] && echo "signature valid" || echo "signature mismatch"
# Also reject deliveries whose timestamp is too old, to block replays.

For more verification code, see Verifying signatures.

Your endpoint should answer with a 2xx status within the webhook’s timeout (10 seconds by default; shown as Timeout in the side sheet). Any other answer, or no answer, counts as a failed attempt and is retried with growing delays, up to 10 attempts.

Test, edit, rotate and delete

Click a webhook’s name to open its side sheet. It shows URL, Secret prefix, Event types, Timeout, Created and Updated, followed by the actions and Recent deliveries.

• Test: sends a signed test request to the endpoint right away, with the event header webhook.test and a body such as {"test":true,"webhookId":"…","triggeredAt":"…"}. A message tells you whether your endpoint accepted it. Test is also on each row of the table.
• Edit: change the name, URL, event types or Active, then click Save. Clear Active to pause deliveries without deleting the webhook.
• Rotate secret: creates a new signing secret. The Rotate webhook secret dialog warns that the current secret stops working immediately. After you click Rotate secret, the Webhook secret rotated dialog shows the new secret once. Click Copy secret, update your endpoint, then click Done.
• Delete: removes the webhook after confirmation. No further events are delivered to the endpoint.

Deliveries

Click to enlarge

Recent deliveries lists the 20 most recent deliveries, newest first. Click Load more to see 20 more, up to 200. Each row shows the event type, the status, when it was created, the number of attempts (for example 3×) when it was retried, and the last error, if any. Click Show payload to see the JSON body that was sent.

Test requests do not appear here; only deliveries of real events do.

API quickstart

The API quickstart section shows a complete request that lists your assets, already pointing at your DeviceQuest address (shown as Example endpoint). Pick a tab and click Copy:

• Direct REST: cURL, JavaScript fetch, Python requests.
• Official SDK: Go SDK.

Each example reads the address from DEVICEQUEST_BASE_URL and the key from DEVICEQUEST_API_KEY. Use the arrow keys, Home and End to move between tabs.

REST API Reference

The REST API Reference lists the public REST endpoints with their Method, Path, Description, Auth and Required scope. Every endpoint needs an API key with the listed scope.

• Type in Filter by path, method, or scope to narrow the list. The count shows how many endpoints match.
• Click a resource chip (All, or a resource such as assets) to show only that resource.

Related pages

• Flows
• Integrations