Quickstart

From zero to a signed, audited verdict in three calls. Everything below runs against the production engine at https://api.fidacy.com.

1 · Create an API key

Sign in to the console, create an organization (one click), and mint a key scoped to assess:write and assess:read. The raw key is shown once — store it as a secret.

# the console at app.fidacy.com → API Keys → Create
fky_live_x8Qd…   (shown once — keep it secret)

Keys are fky_live_… (live) — they authenticate every API call. Never embed a secret key in client-side code or a public repo.

2 · Assess a mandate

Send the AP2 mandate. Authenticate with a Bearer token (or the x-api-key header). The engine validates, scores, signs, and audits — then returns the verdict.

curl https://api.fidacy.com/v1/assess \
  -H "Authorization: Bearer $FIDACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mandate": {
      "vct": "mandate.payment.1",
      "transaction_id": "5f3c…",
      "payee": { "id": "merchant_42", "name": "Acme Corp" },
      "payment_amount": { "amount": 4299, "currency": "EUR" },
      "payment_instrument": { "id": "pi_1", "type": "card" }
    }
  }'

The response carries the decision and the full rich outcome:

{
  "decision": "approve",
  "score": 12,
  "assessmentId": "asmt_0Kc…",
  "mandateId": "mnd_9aZ…",
  "riskPayloadJws": "eyJhbGciOiJFZERTQSJ9.eyJ…",
  "mandate": { …, "risk_data": { "fidacy": { … } } },   // ready to forward
  "outcome": { "object": "assessment", "outcome": { "risk_level": "normal" }, … }
}

3 · Forward the signed mandate

The response’s mandate already has the signed Risk Payload injected into risk_data. Forward it to the payment rail. The receiving party verifies the JWS against your public JWKS — no call back to Fidacy needed.

The verify URL travels inside the payload (risk_payload.verify_url), so any party can fetch the public key by kid and check the signature offline.

The same call over raw HTTP

No SDK required. The endpoint is plain JSON over HTTPS — any language, any runtime. Bearer or x-api-key, a mandate in, a signed verdict out.

Verify the signature yourself

Fetch the JWKS once, cache it, and verify every riskPayloadJws offline against the key named by its kid. Trust the math, not the transport — see Verify a Payload.

Read it back

Assessments are first-class objects. The same rich outcome is reconstructed deterministically from the stored record — useful for dashboards, disputes, and replay.

curl https://api.fidacy.com/v1/assessments/asmt_0Kc… \
  -H "Authorization: Bearer $FIDACY_API_KEY"

Reading the decision