One base URL, one bearer token, one primary verb. Every assessment is a single POST that returns a signed verdict you can verify offline. The surface below is the whole engine — no hidden endpoints, no SDK lock-in.
Every request carries a bearer key in the Authorization header. Live keys are prefixed fky_live_, test keys fky_test_. Keys never appear in a verdict and are never logged.
Authorization: Bearer fky_live_9f2c… Content-Type: application/json Idempotency-Key: ord_20260726_0a91 // optional
Full key handling, rotation and scopes live in Authentication.
The complete surface. Every path is prefixed with the base URL and /v1.
{{ row.path }}
{{ row.desc }}
/v1/assess
The engine's one job. Submit the mandate and context; get back a decision, a risk score, and a detached JWS you can verify without calling us again.
{{ row.field }}
{{ row.type }}
{{ row.meaning }}
POST /v1/assess
{
"mandate": {
"vct": "mandate.payment.1",
"amount": 4200, "currency": "USD",
"payee": "acct_88f1"
},
"agent": { "id": "agt_shopper_02" },
"context": { "session": "sess_7c2" }
}
200{
"decision": "approve",
"risk": 0.12,
"reasons": [ "mandate-valid", "agent-known" ],
"riskPayloadJws": "eyJhbGciOiJFZERTQSJ9..",
"assessment_id": "as_5d0b9c",
"created": "2026-07-26T14:02:11Z"
}
Every verdict resolves to exactly one of three values. Nothing else is ever returned in decision.
approve
Proceed. Risk is within tolerance and the mandate checks out.
review
Step up. Require stronger auth or human approval before continuing.
deny
Blocked. Do not proceed — the mandate or agent failed a hard check.
Errors are structured and typed. The HTTP status tells you the class; the errors[] array tells you exactly what to fix.
{{ row.status }}
{{ row.type }}
{{ row.meaning }}
Send an Idempotency-Key and a retried request returns the original verdict instead of running twice. Keys are honoured for 24 hours. The mandate's content_hash also governs dedup natively.
X-RateLimit-Limit: 600 X-RateLimit-Remaining: 594 X-RateLimit-Reset: 1785074531
The default ceiling is 600 assessments/minute per key. A 429 is safe to retry with backoff — see Scaling.
The riskPayloadJws is a detached EdDSA signature over the assessment. Fetch our public JWKS once, cache it, and verify offline — no callback, no trust in the transport.