Conditional pilot environment — controlled use only.
RiskAlgn™

Developers

RiskAlign Public API v1

A small, tenant-scoped read API plus an inbound webhook slot. Designed for SIEM exports, GRC integrations, and audit-trail mirroring. JSON, Bearer auth, 60 requests per minute per key.

OpenAPI 3.1 specPlatform status

1. Getting a key

An admin on your tenant creates a key in the platform under Admin → API Keys. The full key (format rak_...) is shown once on creation; only its prefix is stored after that.

2. Authentication

curl https://riskalignplatform.com/api/public/v1/risks \
  -H "Authorization: Bearer rak_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Bad or missing key returns 401. Missing scope returns 403. Rate limit (60/min/key) returns 429.

3. Scopes

  • read:risks
  • read:controls
  • read:evidence
  • read:audit-trail

4. Endpoints

MethodPathScopeNotes
GET/api/public/v1/risksread:risksList risks. `?limit=` (max 500), `?updated_since=ISO8601`.
GET/api/public/v1/risks/{id}read:risksSingle risk with linked control IDs and open-issue count.
GET/api/public/v1/controlsread:controlsList controls.
GET/api/public/v1/evidenceread:evidenceList evidence items with linked risks/controls.
GET/api/public/v1/audit-trailread:audit-trailAppend-only audit log for SIEM export. `?since=` and `?limit=` (max 1000).
POST/api/public/v1/webhooks/control-test-resultn/a (HMAC)Inbound webhook. Headers: X-RiskAlign-Tenant, X-RiskAlign-Signature: sha256=<hex>, Idempotency-Key.

5. Errors

All error responses use the shape:

{ "error": { "code": "rate_limited", "message": "Too many requests — limit 60/min." } }

6. Outbound webhooks

Configure subscriptions at /app/admin/webhooks. Every delivery is signed:

  • X-RiskAlign-Signature: sha256=<hex> — HMAC-SHA256 of the raw body using your subscription's signing secret.
  • X-RiskAlign-Event — e.g. review_cycle.closed, evidence.upserted, risk.updated.
  • X-RiskAlign-Delivery-Attempt — 1 for the first try, 2+ for retries.

Retry policy: 1 min, 5 min, 30 min (4 attempts total) on 5xx, 408, 429, or network error. 4xx (other than 408/429) are treated as caller-config errors and not retried. After 20 consecutive failures a subscription is auto-disabled — admins can re-enable from the Webhooks page.

Node verification snippet:

import crypto from "node:crypto";

export function verifyRiskAlign(req, secret) {
  const sig = (req.headers["x-riskalign-signature"] ?? "").replace(/^sha256=/, "");
  const expected = crypto.createHmac("sha256", secret).update(req.rawBody).digest("hex");
  // timing-safe compare
  const a = Buffer.from(sig, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

7. Limits & roadmap

  • 60 requests/min per key (token bucket, best-effort across edge isolates).
  • Read-only in v1. Write endpoints will land when a pilot prospect names one.
  • Per-IP allow-lists and mTLS available on enterprise plans only.