Documentation

Trust Decisions quickstart

Verify a signup before granting access, then report what actually happened.

On this page

0. Get a key

Create a server-side API key with verify:write. Add feedback:write if you will report outcomes. Set CHITMARK_API_KEY in your shell or server environment. Keep it out of browser code.

Use curl to get a first verdict without installing a library, or try a signup in the Trust Decisions playground.

curl -fsS https://api.chitmark.com/v1/verify \
  -H "Authorization: Bearer $CHITMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"signup","session":"signup-demo-1","surface":"app.example.com/signup","subject":{"ipTrunc":"203.0.113.0/24"}}'

1. Install

For application code, install the SDK for your runtime. For direct HTTP, continue with the same endpoint and bearer header.

npm install @chitmark/sdk

2. Client

Create a shared server-side client. Both SDKs default to a challenge when the service is unavailable.

import { Chitmark } from "@chitmark/sdk";

const client = new Chitmark({ apiKey: process.env.CHITMARK_API_KEY! });

3. Verify the action

Send the action and server-collected request context. These examples use sample inputs. In your handler, use a session specific to the attempt and the actual subject.

Persist the returned eventId on the attempt before branching so you can join feedback later. Grant value only on a non-degraded allow. On challenge, hold the grant and require step-up. On deny, stop. On a timeout, error, or degraded result, hold the grant and follow the failure guide.

In an illustrative response excerpt, {"decision":"challenge","eventId":"evt_example","degraded":false} means the service evaluated the action and your app still needs to require step-up.

const verdict = await client.verify({
  action: "signup",
  session: "signup-demo-1",
  surface: "app.example.com/signup",
  subject: { ipTrunc: "203.0.113.0/24" },
});
console.log(verdict.decision, verdict.eventId, verdict.degraded);

4. Feedback when outcomes land

When an actual conversion, credit burn, or other supported outcome occurs, report it using the stored eventId from the original attempt. The example assumes eventId is loaded from your application store and a conversion has occurred.

Verify reference · Feedback reference · Errors and retries

await client.feedback({ eventId, outcome: "converted" });