Fidacy
Open console

Reference

Verify a Payload

Every /v1/assess response includes a riskPayloadJws, a compact JWS (EdDSA) carrying the signed verdict. You can verify it offline against the public JWKS at https://api.fidacy.com/.well-known/jwks.json, proving the decision is authentic without trusting Fidacy and without a call back to the engine.

Why verify

The signature is the trust boundary. The receiving party, a payment rail, a counterparty agent, your own downstream service, does not have to take the verdict on faith. It fetches Fidacy's public key (by kid) and checks the EdDSA signature itself. A valid signature means the decision and every signed field came from the holder of the Fidacy signing key and were not altered in transit. The private key never leaves the engine; the JWKS exposes only the public half.

GET/.well-known/jwks.json

Public, unauthenticated, and cacheable (stable per kid, cache-control: public, max-age=3600). The protected header of the JWS pins alg: "EdDSA" and a kid that selects the verifying key from the set.

Node

Use jose. createRemoteJWKSet fetches and caches the key set; compactVerify checks the signature and returns the raw payload bytes. Install with npm i jose.

import { compactVerify, createRemoteJWKSet } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://api.fidacy.com/.well-known/jwks.json'));

// riskPayloadJws comes from the /v1/assess response
const { payload, protectedHeader } = await compactVerify(riskPayloadJws, JWKS);
const verdict = JSON.parse(new TextDecoder().decode(payload));

console.log('algorithm:', protectedHeader.alg);   // "EdDSA"
console.log('key id:', protectedHeader.kid);
console.log('verified verdict:', verdict);          // { decision, ... }, cryptographically authentic
If compactVerify resolves, the JWS is authentic. If the signature is wrong, the key id is unknown, or the algorithm has been tampered with, it throws, so a verdict you can read is a verdict you can trust.

Python

Use joserfc, a maintained, EdDSA-capable JWS library. Fetch the JWKS, import it as a KeySet, and deserialize the compact JWS against it. Install with pip install joserfc requests.

import json
import requests
from joserfc import jws
from joserfc.jwk import KeySet

# Fetch the public JWKS (cache this, it is stable per kid)
jwks = requests.get("https://api.fidacy.com/.well-known/jwks.json").json()
key_set = KeySet.import_key_set(jwks)

# risk_payload_jws comes from the /v1/assess response
obj = jws.deserialize_compact(
    risk_payload_jws,
    key_set,
    algorithms=["EdDSA"],   # algorithm allowlist, reject anything else
)

verdict = json.loads(obj.payload)
print("algorithm:", obj.headers()["alg"])   # "EdDSA"
print("key id:", obj.headers()["kid"])
print("verified verdict:", verdict)          # { "decision": ..., ... }, authentic
Pin the algorithm to EdDSA on the verifier side (as shown). An open algorithm list is an algorithm-confusion footgun; the engine signs only with EdDSA, so a strict allowlist costs nothing and closes the door.

What you trust

The verified verdict is the source of truth: its decision (approve / review / deny) and the other signed fields are what you act on. They are cryptographically bound to the Fidacy signing key.

  • ·decision and the signed fields, authentic, tamper-proof, verifiable offline. This is what you trust.
  • ·The audit pointer (returned separately, e.g. outcome.audit.entry_id) chains the verdict into Fidacy's tamper-evident, hash-linked log, proof that the decision was recorded, in order, and never rewritten. See Security.

Protected header

For reference, the JWS protected header looks like this, typ marks it as a verifiable-credential JWS:

{ "alg": "EdDSA", "kid": "1zoM57brjllufNTzCwI5-j5jFkiAslyzVDbPAcR_f-M", "typ": "application/vc+jws" }
The full machine-readable contract is published as an OpenAPI 3.1 spec at /openapi.json, import it into Postman, Insomnia, or a codegen toolchain.
Next →Security