Decision API

Turn attestation evidence into a response your backend can use. Learn how to read the API result, interpret signal confidence, and configure decision flows for the actions your app protects.

Configuring decision flows in the Cipherstep Developer Portal.

Reading and enriching evaluations

The Decision API analyzes the attestation envelope your app produces and returns a recommended action with the signals behind it. Your backend combines that result with the account, identity, and transaction context it already has, then decides how the protected request proceeds.

Submit the envelope from your backend to POST /v1/evaluations, then poll GET /v1/evaluations/{evaluationId} for the result. An accepted submission means the request was accepted for processing; it is not an allow decision.

Allow evaluationJSON excerpt

{
  "evaluationId": "6f626279-59b7-4dc3-9557-b2bd7db0a104",
  "userId": "account-access-example",
  "status": "complete",
  "analysis": {
    "decision": "allow",
    "signals": [
      {"type": "integrity_checks_passed", "confidence": 90},
      {"type": "physical_device_observed", "confidence": 95}
    ]
  },
  "analysisVersion": 5,
  "networkPending": false
}

Block evaluationJSON excerpt

{
  "evaluationId": "6f626279-59b7-4dc3-9557-b2bd7db0a102",
  "userId": "account-access-example",
  "status": "complete",
  "analysis": {
    "decision": "block",
    "signals": [
      {"type": "emulator_detected", "confidence": 90},
      {"type": "unique_replay_detected", "confidence": 100}
    ]
  },
  "analysisVersion": 5,
  "networkPending": false
}

Two synthetic evaluations: integrity and physical-device observations support allow; reused attestation evidence triggers block in the foreground example.

status describes processing readiness. Check it before using the analysis, and define how your app handles partial or unavailable results.
analysis.decision returns the action selected by the decision flow. The standard outcomes are allow, review, challenge, and block.
analysis.signals lists findings by type, each with its own confidence. These explain the evidence available to the decision flow.
analysisVersion identifies the analysis version. networkPending indicates whether requested network analysis is still outstanding.

Keep the evaluation ID with the protected action so your team can follow the result. Use the same idempotency key when retrying a submission, and collect a fresh envelope for each new action.

Optional network and user enrichment

Add the end user’s IP address and the JA4 TLS fingerprint observed by your infrastructure through networkData. Network analysis can compare IP location with operating-system observations such as region and timezone, and assess unusual JA4 patterns against the app’s learned network baseline. Together, these findings can surface inconsistencies and activity worth investigating for automation.

Optional partner IP intelligence can be scoped into your integration to add proxy and VPN risk indicators. These provide context about the network behind a request; they do not establish fraud by themselves.

You can also supply user-specific context through userInfo, including values such as IDFV or user email. These values do not automatically become risk signals. If your company wants to use them for analysis, Cipherstep can work with your team to set up a custom workflow around the use case, data handling, and findings you need.

Signal flags and confidence

A signal names what the analysis found, such as emulator_detected or runtime_hooking_detected. Confidence is a 0–100 measure of the strength of that finding. It is not a percentage likelihood of fraud, and a high-confidence environment finding does not establish malicious intent.

Some findings come from exact checks. For example, unique_replay_detected can carry confidence 100 when an authenticated attestation session has already appeared in another evaluation. That value reflects certainty about the reuse being reported.

Other findings use adaptive baselines built from eligible observations of your app’s environment and activity. As representative data flows through the system, those baselines gain support and confidence can strengthen. Confidence also depends on evidence coverage and how far an observation departs from the learned pattern; more traffic does not automatically raise every signal’s confidence.

The appropriate response depends on the action you are protecting. You might reject emulated devices during KYC, while permitting login from an emulator when the required runtime checks and your other controls are satisfied. That is a policy choice, not a different meaning for the emulator flag.

Cipherstep works with your team to scope the signals, thresholds, and assurance requirements for each use case. We help distinguish direct tampering evidence from environment restrictions, unusual patterns, and missing coverage, so the response fits the risk of the action.

Customize decision flows in the Developer Portal

Decision Flows lets your team configure how findings become API outcomes. Adjust signal mappings and confidence thresholds, define custom decision labels, and choose how to handle unknown signals, insufficient assurance, and findings below a threshold.

Create separate flows for actions such as KYC and login, then select the appropriate flow when your backend submits an evaluation. Custom labels retain an underlying allow, review, challenge, or block class; your integration should handle the labels it is configured to receive.

Each evaluation retains the selected flow and its revision. Saved changes apply to new evaluations, keeping the policy behind an existing result traceable. Flow configuration changes the customer-facing action; it does not rewrite the underlying signal confidence or the baselines used for analysis.

We work with your team on these choices before enforcement, including fallback behavior and the handling of incomplete evidence. The portal gives you control over the flow; Cipherstep helps make it appropriate for your app and the requests you need to protect.