API Documentation

Authentication

Send a personal API token (pat_...) in either header: Authorization: Bearer pat_... or X-API-Key: pat_.... A token acts as the user who created it, in the organization it was created in, and never with more rights than that user's role there. Tokens are created, listed and revoked from a signed-in browser session only. A token can expire, and revoking it takes effect on the next request.

Give each token only the scopes it needs. A token with no scope list (all tokens issued before scopes existed) has its owner's full non-admin access. A scoped token is refused, with 403 INSUFFICIENT_SCOPE, by every endpoint outside its scopes.

Token management and approving exceptions or suppression rules never accept an API token, whatever its scopes (PAT_NOT_ALLOWED, PAT_CANNOT_APPROVE). Administration is not reachable with a token at all: those routes answer 404, as they do for any non-admin.

Scan, Poll, Export

1. Start a scan (scan:write). POST /validation/single with {"domain": "example.com"}, or POST /validation/batch with {"domains": ["a.example", "b.example"]}. Both answer with a validation_id. A batch also lists the rejected_domains it will not scan, and why. A name that cannot be scanned is refused before any quota is spent (see the DOMAIN_* codes under Errors).
2. Poll (scan:read). GET /validation/jobs/{validation_id}/status until status is SUCCESS, FAILURE, REVOKED or CANCELLED; PENDING and PROGRESS mean keep waiting. Poll every 5 to 10 seconds, or subscribe to the scan.completed webhook instead. A single-domain scan usually takes 2 to 5 minutes.
3. Read findings (findings:read). GET /validations/{validation_id}/findings returns one row per check with check_id, status (pass, partial, fail, not_applicable, not_tested, unknown), severity and evidence. For a batch, add ?domain=.
4. Export (reports:read). GET /validations/{validation_id}/export?format=... for one scanned domain:

Whole-validation reports (PDF, HTML, JSON, CSV, XLSX; batches as one file or a zip) come from POST /reports/{validation_id}/export?format=pdf.

What an export proves

• Lifecycle is as of export time. Finding state, owner, due date and exceptions belong to the asset, not to the scan, so every export shows the state at the moment you export, not at the moment the scan ran. Exporting an older scan shows today's owner, due date and exceptions, and its OSCAL risks leave out findings closed since. Each format says so itself: SARIF in runs[0].properties.lifecycle_as_of_note, OSCAL in metadata.remarks, XLSX on the About sheet, the bundle in manifest.json (lifecycle_as_of_note), the coverage report API response in as_of_note (next to exceptions_as_of), and the HTML and PDF reports in the introduction of their coverage section.
• The evidence bundle is hash-chained but not signed. manifest.json lists the SHA-256 of every member, and the findings fold into a Merkle root that is compared with the root sealed when the scan completed. That proves the files are intact and match what the server held for this scan (integrity against the server). It does not prove who produced the bundle (authorship): there is no digital signature, so a party who can rebuild a manifest can rebuild a self-consistent bundle. manifest.json states this in integrity.signed (false) and integrity.authenticity_note. Treat a bundle that reached you from someone else as a claim, not as proof: export the same scan yourself and compare the Merkle roots.

curl -s "/api/v1/validations/4711/export?format=sarif&fail_on=high" \
  -H "Authorization: Bearer $SETENFORCE_TOKEN" -o setenforce.sarif

Webhooks

Add a webhook under Notification channels (or POST /notifications/channels with webhooks:write). Only organization owners and admins can create, edit or test a webhook (others get 403 ROLE_CANNOT_MANAGE_WEBHOOKS); the role is checked in the active organization, and finding.* events are delivered only while the webhook's owner is an owner or admin of the finding's organization. Each webhook is an HTTPS POST of a JSON body {"id", "type", "created_at", "data"}. Events: scan.completed, finding.opened, finding.fixed, finding.state_changed, exception.expiring, alert.raised, certificate.expiring (and webhook.test from the Test button).

X-SetEnforce-Signature: t=<unix time>,v1=<hex>, where v1 is HMAC-SHA256 of "<t>." + raw body keyed with your whole whsec_... secret. Verify against the raw bytes before parsing the JSON, compare in constant time, and reject a t more than 5 minutes from your clock to stop replays. Delivery is at-least-once: dedupe on X-SetEnforce-Event-Id. Answer with any 2xx within 10 seconds.

Retries and dead-letter

A delivery is attempted up to 5 times in all: the first send and four retries. After a failed attempt (no 2xx within 10 seconds, or a connection error) the retry comes 1 second, then 10 seconds, then 1 minute, then 10 minutes later, each delay varied by up to 20% either way. If the fifth attempt fails too, the delivery is dead-lettered: it is marked failed, kept in the delivery log under Notification channels for 30 days, and never sent again. A delivery is also dead-lettered without further attempts when the webhook is disabled or its owner no longer holds the role needed to receive that event. Every attempt re-sends the same body and the same X-SetEnforce-Event-Id. The Test button sends once and does not retry.

# Python
import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts["t"])
    if abs(time.time() - t) > tolerance:
        return False  # too old (or too new): possible replay
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

// Node.js (rawBody: the request body as a Buffer, before JSON.parse)
const crypto = require('crypto');

function verify(secret, rawBody, header, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=', 2)));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Pagination

List endpoints take limit (page size) and cursor, and answer with items and next_cursor. To read everything, pass each response's next_cursor back as cursor until it is null. Keep the other query parameters (filters, sort) the same on every page. Treat the cursor as opaque: its format may change. A cursor this API did not issue is refused with 400 INVALID_CURSOR.

cursor=""
while :; do
  page=$(curl -s "$BASE/validation/jobs?limit=100${cursor:+&cursor=$cursor}" -H "Authorization: Bearer $SETENFORCE_TOKEN")
  echo "$page" | jq -c '.items[]'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Apart from GET /reports/ (see Versioning), these endpoints also keep the paging parameters they had before (offset, skip, page and page_size) and fields such as total; a cursor wins over them. Short, bounded lists (your organizations, members, tokens, notification channels, suppression rules, one scan's findings) return every item at once.

Rate Limits

Every API response carries your request budget for the current one-minute window:

• RateLimit-Limit: requests allowed per minute.
• RateLimit-Remaining: requests left in this window.
• RateLimit-Reset: seconds until the window resets.

The budget is per API token, so one busy integration never slows down another or your own use of the web app. Its size is your plan's requests per minute:

Past the budget an API token gets 429 RATE_LIMITED. Every 429 carries Retry-After (seconds): wait that long, then retry. Some endpoints have their own tighter limit (scan submission, sign-in, sending a test notification). A 429 from such a limit reports that limit in its RateLimit-* headers. Scans are also bound by daily quotas (QUOTA_EXCEEDED, BATCH_QUOTA_EXCEEDED) and by how many may run at once (CONCURRENT_LIMIT_EXCEEDED); GET /quota/status shows where you stand. Browser sessions see the same headers for information; they are not throttled by this budget.

Idempotency

POST /validation/single and POST /validation/batch accept an Idempotency-Key header (any unique string up to 255 characters; a UUID works). If a request times out or your pipeline step is retried, send it again with the same key: you get the first response back, with Idempotent-Replayed: true, and no second scan starts or counts against your quota.

• Keys are remembered for 24 hours, per user and per endpoint.
• Only a successful response is remembered. If the first attempt failed (for example QUOTA_EXCEEDED), the retry runs again for real.
• The same key with a different body, or from another organization, is refused with 422 IDEMPOTENCY_KEY_REUSED.
• A retry that arrives while the first request is still running gets 409 IDEMPOTENCY_KEY_IN_PROGRESS; retry it a moment later.

Errors

Errors use the HTTP status codes you would expect, and every error body has a stable, machine-readable code. Branch on code, not on the human-readable message or detail, whose wording may change. Most errors look like this:

HTTP/1.1 403 Forbidden
{
  "error": "PatScopeException",
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API token lacks the 'scan:write' scope",
  "details": {"code": "INSUFFICIENT_SCOPE", "required_scope": "scan:write"},
  "path": "/api/v1/validation/single"
}

Some older endpoints answer {"detail": ..., "code": ...} instead, where detail is a message or an object. code is always at the top level. New codes may be added at any time, so treat an unknown code like the generic code for its HTTP status.

Versioning

The version is in the path: /api/v1. Within v1 we only make changes that a well-behaved client absorbs without a code change:

• new endpoints, new optional parameters and new headers;
• new fields in responses and webhook payloads (ignore fields you do not know);
• new checks, controls, frameworks, webhook event types and error codes;
• new values for a deprecated alias's replacement, never a change to the alias itself.

These need a new API version, and will not happen within v1:

• removing or renaming an endpoint, a parameter or a response field, or changing a field's type;
• changing the status vocabularies: job status (PENDING, PROGRESS, SUCCESS, FAILURE, REVOKED, CANCELLED), finding status and severity, finding lifecycle states;
• renaming, reusing or changing the meaning of a check_id or a control id. A check id is an external interface: when a check is replaced, the new check gets a new id and the old id is retired, never recycled;
• changing what an error code means, or what a token scope grants.

Breaking change in v1: GET /reports/

GET /reports/ used to return a bare JSON array of at most 50 reports. It now returns an object, {"items": [...], "next_cursor": null}, like the other paginated lists: read the reports from items and follow next_cursor for the rest (default limit 50, maximum 200). A client that parses the response as an array breaks, and unlike the other lists this one keeps no old-shape fallback. This change does not follow the rules above; we made it on purpose and record it here.

Deprecated fields and parameters keep working for the life of v1. Today these are the validations, offset and has_more fields of GET /validation/jobs, and the offset, skip, page and page_size parameters, replaced by cursor and limit. A security fix may tighten behaviour without a version change.