Scan API

The Scan API is available on every plan, including Free. What changes with the plan is how many scans a month you get — see scan classes, allowances and credits and pricing. Every request is checked against your plan's scanning entitlement; a plan without it is answered 403 plan_required.

1. Create a secret scan API key

Keys are created from your signed-in AccessWiser account. A key needs a label (1–60 characters, e.g. CI pipeline) and a lifetime — 7, 30, 60 or 90 days, or never expires. You can hold up to 10 live keys at once and revoke any of them at any time. If you can't find the screen in your account, email us and we will sort you out.

The secret looks like awsk_… and is shown exactly once. We store only a keyed hash of it, so a lost key is replaced, never recovered — not even by us. Treat it like a password: environment variable or secret store, never a commit.

2. Register and verify your domain

Registering a domain on your account is an assertion. Verifying it is evidence, and the API wants the evidence. Publish the DNS TXT record your account generates for that domain — either on the _accesswiser subdomain or on the bare domain — and run the check:

Name:  _accesswiser.example.com
Type:  TXT
Value: accesswiser-site-verification=<the token shown in your account>

The token is unique to your account and that domain, so no other account can verify with it. Verifying a domain also covers its subdomains, since they share the same zone of authority. Until the check passes, every scan request for that host is refused with 403 domain_not_verified— before anything is sent to the target site. Every scan and every refused attempt is written to your account's audit log with the key that made it.

3. Make your first request

Send an Idempotency-Key from CI (a git SHA works well). It is optional, but it is what stops a pipeline retry from paying for a second scan.

curl -X POST https://app.accesswiser.com/api/v1/scans \
  -H "Authorization: Bearer awsk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-${GITHUB_SHA}" \
  -d '{
    "url": "https://example.com/pricing",
    "scanClass": "quick"
  }'

You get back:

HTTP/1.1 202 Accepted
Location: /api/v1/scans/6f1c0f6e-6c2c-4a3b-9f5a-2a1d3b4c5d6e
X-Scan-Class: quick
X-Scan-Allowance-Limit: 400
X-Scan-Allowance-Remaining: 397
X-Scan-Allowance-Reset: 2026-08-01T00:00:00.000Z
X-Scan-Credits-Remaining: 0

{
  "scanId": "6f1c0f6e-6c2c-4a3b-9f5a-2a1d3b4c5d6e",
  "status": "running",
  "scanClass": "quick",
  "url": "https://example.com/pricing",
  "chargedTo": "allowance",
  "allowanceRemaining": 397,
  "credits": 0,
  "statusUrl": "/api/v1/scans/6f1c0f6e-6c2c-4a3b-9f5a-2a1d3b4c5d6e",
  "disclaimer": "Automated testing detects only a portion of ..."
}

Then poll statusUrl until terminal is true.

Pass a webhookUrl when you create a scan and we will call it when the scan reaches a terminal state, so your job does not have to poll:

curl -X POST https://app.accesswiser.com/api/v1/scans \
  -H "Authorization: Bearer awsk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "scanClass": "evidence",
    "webhookUrl": "https://ci.example.com/hooks/accesswiser"
  }'

The URL must be https and must resolve to a public address. We validate it while handling your request, so a callback we cannot deliver to fails the create with a 400 rather than leaving you waiting for a call that will never come. Redirects are not followed.

What a delivery looks like

POST /hooks/accesswiser HTTP/1.1
Content-Type: application/json
User-Agent: AccessWiser-Webhook/1
X-AccessWiser-Event: scan.completed
X-AccessWiser-Delivery: 0f2a9c31-7b4e-4f6a-8d21-9c0b5e7a1234
X-AccessWiser-Timestamp: 1785495269
X-AccessWiser-Signature: t=1785495269,v1=9c1f...

{
  "event": "scan.completed",
  "customerId": "b6f0d0a2-1d4e-4b8f-9a10-2c3d4e5f6a7b",
  "scanId": "6f1c0f6e-6c2c-4a3b-9f5a-2a1d3b4c5d6e",
  "status": "completed",
  "url": "https://example.com/pricing",
  "scanClass": "evidence",
  "healthScore": 82,
  "summary": {
    "totalIssues": 14,
    "critical": 1,
    "serious": 4,
    "moderate": 6,
    "minor": 3,
    "incomplete": 2
  },
  "error": null,
  "completedAt": "2026-07-31T09:14:29.884Z",
  "disclaimer": "Automated testing detects only a portion of ..."
}

The event is scan.completed or scan.failed. X-AccessWiser-Delivery is stable across retries of the same delivery, so use it to deduplicate.

The payload carries the counts, not the findings — a webhook body has to stay small enough to deliver and retry reliably. Take the delivery as the signal that the scan is done, then read the findings from GET /scans/{id}.

Verifying the signature

Signing uses HMAC-SHA256 with a secret that is unique to your account (available alongside your API keys in your account) — never a secret shared between customers, so nobody else can mint a delivery your receiver would accept. The steps, in order:

1. Read the raw body. Do not parse and re-serialise the JSON first — key order and whitespace are part of what was signed.
2. Split X-AccessWiser-Signature on commas into its k=v pairs and take t and v1. Ignore versions you do not know.
3. Reject if t is more than 300 seconds from your own clock. Compare against t from the signature, not the timestamp header — they are equal, but only t is inside the signed string.
4. Build the signed string as exactly `${t}` + "." + rawBody — an ASCII full stop, no trailing newline.
5. Compute HMAC-SHA256 over it with your signing secret, lower-case hex, and compare to v1 with a constant-time comparison.
6. Only then parse the JSON.
7. Check that customerId in the body is your account id. The signature proves the delivery came from us; this proves it was meant for you.

const crypto = require("crypto");

// Verify an AccessWiser scan webhook.
//   rawBody         the request body as received, NOT re-serialised JSON
//   signatureHeader the X-AccessWiser-Signature value, e.g. "t=...,v1=..."
//   secret          your account's webhook signing secret
function verify(rawBody, signatureHeader, secret, toleranceSec = 300) {
  const parts = {};
  for (const pair of signatureHeader.split(",")) {
    const i = pair.indexOf("=");
    if (i === -1) continue;
    parts[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
  }

  // 1. The timestamp is inside the signature, so it cannot be moved forward
  //    by an attacker replaying a captured delivery.
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  // 2. The signed string is `${t}.${rawBody}` — a full stop, no newline.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  // 3. Constant-time compare. A plain === leaks the digest byte by byte.
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(String(parts.v1 || ""), "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: keep the RAW body, then verify before parsing.
app.post(
  "/hooks/accesswiser",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body.toString("utf8");
    const ok = verify(raw, req.get("X-AccessWiser-Signature") || "", SECRET);
    if (!ok) return res.status(401).end();

    const payload = JSON.parse(raw);
    // 4. The signature proves it came from us; this proves it was meant for you.
    if (payload.customerId !== MY_CUSTOMER_ID) return res.status(401).end();

    // X-AccessWiser-Delivery is stable across retries — deduplicate on it.
    res.status(200).end();
  },
);

Retries

Up to four attempts in total, backing off 1s, 5s then 25s, each with a 10-second timeout. We retry on a timeout, on 429 and on 5xx. Any other 4xx is not retried — you understood us and refused. Delivery is best effort; GET /scans/{id} remains authoritative.