Skip to Content
RiskPolicy authoring

Author risk policies with JSON

The visual editor and API use the same JSON policy definition. An agent can prepare a definition, validate it, test synthetic scenarios, and hand the draft to a reviewer in the visual editor.

Explicit eligibility criteria

Risk and eligibility answer different questions. For example, a client may offer a sale to US residents only. Someone who lives in Canada can have a low risk score and still be ineligible for that sale. A US resident can satisfy the eligibility criteria while a separate risk rule requests review.

Add eligibility to the policy definition to declare participation criteria. Every criterion must pass for the result to be eligible. Use a declared, required input from a source you trust. For this example, residence_country should be a country input: a document’s issuing country or a visitor’s IP location does not establish where that person lives.

{ "eligibility": [ { "id": "residency", "reason": "This offering accepts US residents", "all": [ { "fact": "residence_country", "operator": "eq", "value": "US" } ] } ] }

An assessment with these criteria includes result.eligibility, with its status, criterion results, missing evidence and validity deadline:

StatusMeaning
eligibleEvery configured criterion passed using usable evidence.
ineligibleAt least one condition failed using usable evidence. This remains adverse even if another condition is unresolved.
unknownNo condition has resolved as failed, and at least one condition is unresolved.

Every condition in a criterion’s all list must pass for that criterion to pass. A failed condition establishes a failed criterion even when another condition is unresolved. Missing, expired, revoked or conflicting evidence cannot establish a passed condition. A correction changes the next assessment; an identical request retry returns the original result. Check assessment currentness before using it.

Without explicit criteria, the assessment omits eligibility. A low risk score does not imply eligibility. Treat omitted or unknown eligibility as unresolved when your application requires it. Review the risk decision and completeness alongside eligibility before allowing an action.

Policies support up to 20 eligibility criteria, with up to 20 conditions each. Criteria use the same comparisons and source, type and freshness requirements as risk rules. They do not add risk points, actions or a legal determination.

Discover the contract

GET /api/v1/risk/policy-schema returns schemaVersion, schema and a short explanation. The schema property is a JSON Schema document suitable for editor validation; its identifier is urn:korala:risk-policy:1.

Set schemaVersion: "1" in new definitions. This is the format version, not the revision of a customer’s policy. Older definitions without this property are interpreted as format version 1. Unsupported versions are rejected.

JSON Schema describes the shape, allowed operators and bounds. The server also checks relationships between fields, such as matching input types, increasing band thresholds and references to real workspace verification fields. Always call the validation endpoint before treating generated JSON as valid.

GET /api/v1/risk/verification-inputs lists the current workspace’s configured Korala fields in the credential’s environment. The response contains items and nextOffset. Pass a non-null nextOffset as ?offset=... to load the next page, even when items is empty: a page can contain workflows with no supported fields. Use the returned workflow ID, version timestamp, step index, step type and field in a native input binding. Copy its source into acceptedSources; use ageSource when you set the age_years transform. These source IDs bind the exact workflow version, field and transform. Copy workflowUpdatedAt as the returned string, including its six fractional digits. Converting it through a JavaScript Date loses precision. If an existing binding has only three fractional digits, refresh the catalog and publish a new policy version with its current binding. Korala refuses the ambiguous binding and preserves earlier assessment history. Do not invent workflow IDs or use another workspace’s bindings. External input keys are defined by your integration and declared in its registered source. See evidence sources for both external and native ingestion.

Validate without saving

POST /api/v1/risk/policies/validate Content-Type: application/json { "definition": { "schemaVersion": "1", "inputs": [], "factors": [], "bands": [] } }

The deliberately incomplete definition above returns valid: false and an errors array. Each error has a path and message. Structural errors identify a JSON Pointer; relationship checks may identify the whole definition or its inputs. Valid responses include the normalized definition, including defaults.

Validation creates no policy version. It requires authentication but no idempotency key. Native bindings are checked against the authenticated workspace and test/live environment. A changed workflow requires selecting its field again.

Simulate synthetic scenarios

POST /api/v1/risk/policies/simulate accepts the definition and up to 20 scenarios:

// `definition` is the policy JSON you want to test. const validation = await client.risk.validatePolicy({ definition }); if (!validation.valid || !validation.definition) { throw new Error(JSON.stringify(validation.errors)); } const simulation = await client.risk.simulatePolicy({ definition: validation.definition, scenarios: [{ name: 'Missing evidence', at: '2026-01-01T12:00:00Z', observations: [], }], });

Each scenario provides a fixed evaluation time and at most 200 observations. An observation contains fact, source, status, value, and observedAt; receivedAt and expiresAt are optional. Accepted statuses are available, unavailable and revoked. A boolean false is evidence; absent evidence is not. Supply only the latest receipt for each fact/source pair, as selected evidence would be supplied to a saved assessment. Duplicate pairs are rejected; use separate scenarios to simulate successive receipts or revocation.

For a registered external source, include matching provenance on the synthetic observation. Use the registration ID from its registered:<id> source, a positive registration revision and an API-key ID. For example:

{ "provenance": { "sourceRegistrationId": "00000000-0000-4000-8000-000000000001", "sourceRevision": 1, "assertedBy": "api_key:00000000-0000-4000-8000-000000000002", "adapter": "registered-external-v1", "evidenceClass": "assertion" } }

Replace the registration ID with the one your policy accepts. Omit this metadata or name another registration to test invalid_source_attribution. Synthetic metadata describes a hypothetical receipt; it does not prove that a submission happened. Korala assigns this attribution when you submit real evidence.

For an input with evidenceKind: "model_signal", include modelProvenance on its synthetic observation. Supply provider, model, criteriaVersion, inputDigest (64 lowercase hexadecimal characters), and runId, as you would when submitting that signal. For example:

{ "modelProvenance": { "provider": "example-provider", "model": "example-model", "criteriaVersion": "signal-criteria-1", "inputDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "runId": "synthetic-run-1" } }

Leave modelProvenance out to test the missing_model_provenance gap. Korala rejects malformed metadata. Supplying valid metadata does not bypass accepted-source, receipt attribution, status or freshness checks. In a simulation, this metadata is hypothetical: Korala does not call the model or verify that the claimed run happened.

The response has simulation: true. Each scenario includes applicability and an evaluation explaining input selection, missing evidence, factor contributions, matched rules, band, decision and requested action keys. Evaluate applicability alongside the result: a policy that does not apply must not authorize an action.

Simulation uses the same evaluator as saved assessments, but only on the supplied synthetic observations. It does not read a customer’s evidence, invoke verification providers, save assessments, create action requests, or send webhooks. Source strings in a simulation are hypothetical, not authenticated proof. These results must never be used to authorize customer activity.

Check expected outcomes

Add an optional expected object to a scenario to check for regressions when you change a policy. Choose any of status, decision, score, band, actions, and applicability. Supply at least one field. For example, a policy with a required input should keep missing evidence unresolved:

const simulation = await client.risk.simulatePolicy({ definition, scenarios: [{ name: 'Missing required evidence', at: '2026-01-01T12:00:00Z', observations: [], expected: { status: 'incomplete', decision: 'awaiting_evidence', score: null, band: null, actions: [], }, }], }); const failures = simulation.scenarios.flatMap(scenario => (scenario.checks ?? []).filter(check => !check.matched), ); if (failures.length) throw new Error(JSON.stringify(failures));

Each comparison in checks includes field, expected, actual, and matched. Korala compares only the fields you supply. score: null checks for an absent score; it does not mean zero. Action comparisons require the exact set of keys, regardless of order. Duplicate expected action keys are invalid.

A scenario without expected returns checks: null: it has no regression checks. Include expectations on the cases you want your test runner to enforce. A mismatch returns a successful simulation response with matched: false; it does not change the calculated result or publish a policy. Check applicability separately when policies select a scope: its values are matched, not_matched, or unknown. Passing synthetic cases establishes behavior for those cases, not model accuracy or permission to authorize an activity.

Review and publish

Use Edit policy JSON in the policy editor to paste or copy a definition. Validate and apply updates the visual editor without saving or publishing. The setup order is Inputs, Risk bands, Scoring, Rules, Freshness, Review.

POST /api/v1/risk/policies saves a draft; publication remains a separate request to POST /api/v1/risk/policies/{id}/publish. Both require an owner/admin dashboard JWT and an idempotency key. API keys can discover, validate and simulate policies; they cannot create or publish policies. These endpoints do not add OAuth/MCP permissions: assistant access remains governed by the assistant scope policy.

The TypeScript client exposes risk.policySchema(), risk.verificationInputs(), risk.validatePolicy({ definition }) and risk.simulatePolicy({ definition, scenarios }). Use the existing draft and publication methods for governance. Test credentials remain confined to test mode.

Required and supporting evidence

Set an input’s requirement to required or supporting. Omit it to require that input. Each policy needs at least one required input. A required input must have usable evidence before Korala can produce a complete score.

Use supporting inputs for reviewer context. Missing, stale, revoked or conflicting supporting evidence does not block the score. The assessment’s coverage lists each input’s requirement, availability and gap reason. Korala retains the selected receipts in inputs so reviewers can inspect their sources. A complete assessment means the policy’s required inputs were usable; it does not mean that Korala approved identity or found no risk.

{ "key": "account_context", "type": "string", "requirement": "supporting", "acceptedSources": ["registered:<source-id>"], "maxAgeSeconds": 86400 }

Supporting inputs cannot appear in score factors, rules, applicability conditions or comparisons with other inputs. Mark a fact required before using it to influence a decision. The validation endpoint checks these relationships. In the visual editor, select Required or Supporting context under Evidence requirement. The policy review diagram shows the choice for each input. The assessment page shows available facts and coverage gaps.

Available supporting evidence can shorten the assessment’s validity so monitoring updates its context when it expires. An existing supporting gap does not make an otherwise complete assessment expire. Source acceptance, evidence types and freshness checks apply to both requirements.

Use an exact-reuse review lead

For a US onboarding flow, your integration can submit a document identifier through a registered evidence source. Use a preconfigured exact-reuse profile for that identifier, then use its observed match count in a policy you call Fraud Review.

For example, Alice and Bob submit the same identifier. Alice’s policy receives one observed match: another subject submitted that identifier. You can add a rule that requests review when the count is at least one. If Bob corrects his identifier, Alice’s next assessment receives zero observed matches. Enable monitoring for this policy and its composition to request reassessment when the observed matches change. A later matching submission can bring the count back above zero.

Ask Korala for a profile ID configured for your workspace and environment. Profile creation and management are not available through the public API or dashboard. Declare a number input with the profile selector and its exact source:

{ "key": "document.observed_reuse", "type": "number", "acceptedSources": [ "korala:derived-reuse:5d822de1-e388-436d-aa7a-5c644e2d126c" ], "derivedReuse": { "profileId": "5d822de1-e388-436d-aa7a-5c644e2d126c", "output": "observed_match_count" }, "maxAgeSeconds": 3600 }

For this input, maxAgeSeconds limits the age of the detector measurement. Korala can measure unchanged, usable evidence again. The configured profile’s freshness and expiry limits still apply to the underlying evidence. A new measurement does not extend that evidence’s lifetime or make unavailable evidence usable.

Validate the complete policy before publication. Korala obtains this input from your configured detector. An external submission with the same fact name cannot supply the detector result.

Treat a match as a reason to investigate. Shared document identifiers, accounts or IP addresses can have legitimate explanations. Zero observed matches does not establish uniqueness or authenticity. Korala reports unknown collection coverage and identifies the count as a lower bound on observed matches.

When Korala cannot obtain usable detector evidence, the input has a null value and an availability gap. Keep identity verification in a separate policy and compose it with Fraud Review. A policy using derived reuse can also use registered assertions. Use separate policies for native verification and screening. Korala does not support context-policy assignment or applicability conditions based on derived reuse inputs. The composition retains each policy’s evidence and decision; unknown eligibility remains unknown and cannot grant clearance.

Last updated on