Every request, signed.

Secure Raven cannot show or recover a private key. If one is lost or exposed, revoke the key and mint a new one. Revocation is final. A key’s scopes and public key never change after mint, and its expiry can only move earlier.

Headers

v2|METHOD|pathname|timestamp|nonce|content-type|sha256(body)|tokenId|2

• The pathname is the URL path without the query string: /api/v1/findings.
• GET, HEAD and DELETE sign an empty body, so their digest is always e3b0c442…b855.
• Sign the content type as application/json, even on GET. A request sent with any other content type is refused.
• sha256(body) is the lowercase hex digest of the exact body bytes you send.
• The organization comes from the key. Never send tenant_id.
• There is no HMAC mode, no legacy v1 and no bearer-only mode.

In Node.js 18 or later

import { createHash, createPrivateKey, randomUUID, sign } from "node:crypto";

// The three values shown once when the key was minted
const token = process.env.RAVEN_BEARER;
const tokenId = process.env.RAVEN_TOKEN_ID;
const raw = process.env.RAVEN_SIGNING_KEY.slice("sr_sign_".length);
const key = createPrivateKey({
  key: Buffer.from(raw, "base64url"),
  format: "der",
  type: "pkcs8",
});

const timestamp = String(Math.floor(Date.now() / 1000));
const nonce = randomUUID();
// GET, HEAD and DELETE sign an empty body
const body = "";
const digest = createHash("sha256").update(body).digest("hex");

const message = [
  "v2", "GET", "/api/v1/findings", timestamp, nonce,
  "application/json", digest, tokenId, "2",
].join("|");
const signature = sign(null, Buffer.from(message), key).toString("hex");

// The query string is not part of the signed pathname
const res = await fetch("https://secureraven.app/api/v1/findings?status=open", {
  headers: {
    authorization: `Bearer ${token}`,
    "x-raven-timestamp": timestamp,
    "x-raven-nonce": nonce,
    "x-raven-token-id": tokenId,
    "x-raven-signature": signature,
  },
});

# OpenSSL 3. Ed25519 signs a file, not a pipe.
umask 077
printf '%s' "${RAVEN_SIGNING_KEY#sr_sign_}" | tr '_-' '/+' | base64 -d \
  | openssl pkey -inform DER -out key.pem
printf '%s' "$canonical" > msg.txt
signature="$(openssl pkeyutl -sign -inkey key.pem -rawin -in msg.txt \
  | od -An -v -tx1 | tr -d ' \n')"
rm -f key.pem msg.txt

A nonce is spent even when a request is refused for the rate limit. Every retry needs a new timestamp, nonce and signature.

• By design
  No SQL, REST or row passthrough. There is no /query, /sql or /rest. The API never forwards a query to your database and never returns rows.
• By design
  No secrets on the way out. No decrypted credentials and no full event payloads.
• Not in v1
  No controls or evidence routes. Controls and evidence exports stay in the dashboard.
• Not in v1
  No webhooks and no SDKs. Poll instead, as in the CI release gate below.
• By design
  A passing test authorizes nothing. A successful connection test never turns on Watch, Shield or a scan.
• By design
  No Full Active scans from a key. API keys enqueue safe_all_surfaces only. full_active cannot be started with an API key.

1. Keep the sr_live_… bearer token, the sr_sign_… private key and the token id in your CI secret store. Never commit them.
2. Call GET /api/v1/findings?status=open with a fresh signature. The signed pathname is /api/v1/findings, without the query string.
3. Count the rows whose severity is critical or high. Fail the job if there are any.
4. Log counts by severity only. Titles and remediation are confidential, so keep them out of public logs.
5. The list holds at most 100 rows. If you get 100, fail and ask a person to look: never assume the rest are low.

#!/usr/bin/env bash
# Fail the build on open critical or high findings. Needs OpenSSL 3, curl and jq.
# RAVEN_BEARER, RAVEN_SIGNING_KEY and RAVEN_TOKEN_ID come from your CI secret store.
set -euo pipefail
umask 077
work="$(mktemp -d)"
trap 'rm -rf "$work"' EXIT

ts="$(date +%s)"
nonce="$(openssl rand -hex 16)"
# SHA-256 of the empty body that every GET signs
empty="e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
printf '%s' "v2|GET|/api/v1/findings|$ts|$nonce|application/json|$empty|$RAVEN_TOKEN_ID|2" \
  > "$work/msg"
printf '%s' "${RAVEN_SIGNING_KEY#sr_sign_}" | tr '_-' '/+' | base64 -d \
  | openssl pkey -inform DER -out "$work/key.pem"
sig="$(openssl pkeyutl -sign -inkey "$work/key.pem" -rawin -in "$work/msg" \
  | od -An -v -tx1 | tr -d ' \n')"

curl -fsS "https://secureraven.app/api/v1/findings?status=open" \
  -H "Authorization: Bearer $RAVEN_BEARER" \
  -H "x-raven-timestamp: $ts" -H "x-raven-nonce: $nonce" \
  -H "x-raven-token-id: $RAVEN_TOKEN_ID" -H "x-raven-signature: $sig" \
  -o "$work/findings.json"

# Counts by severity only. Titles and remediation stay out of public logs.
jq -r '.findings | group_by(.severity) | map("\(.[0].severity)=\(length)") | join(" ")' \
  "$work/findings.json"
total="$(jq '.findings | length' "$work/findings.json")"
blocking="$(jq '[.findings[] | select(.severity == "critical" or .severity == "high")] | length' \
  "$work/findings.json")"
if [ "$total" -ge 100 ]; then echo "100 rows is the cap: failing rather than guessing"; exit 1; fi
if [ "$blocking" -gt 0 ]; then echo "$blocking open critical or high findings"; exit 1; fi
echo "No open critical or high findings"

• The signed pathname is always the constant /functions/v1/<function>, whatever URL the request travels through.
• A probe key carries only the ingest scope, is bound to one system, and expires after a year.
• In this mode Secure Raven holds a hash of the probe’s token and its Ed25519 public key. No database password.

Questions about the API? Write to support@secureraven.app, or read how Secure Raven secures itself.