> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authmatech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Identity Intelligence: Trust, Shield & Detect

> Score confidence, decide on fraud risk in real time, and detect behavior anomalies using Authmatech Trust, Shield, and Detect from the same session signals.

Once you can [verify](/guides/verify) identity, layer in intelligence. Trust, Shield, and Detect accept the same `device` and `network` signal model, so you collect context once and reuse it across calls. For the conceptual differences, see [Identity intelligence](/concepts/identity-intelligence).

<Note>
  The exact signals, thresholds, and weights behind these products are intentionally **not published** — that's what keeps them hard to game. Build against the documented outputs (`trustScore`, `decision`, `anomalies`, `reasonCodes`); treat the scoring internals as opaque.
</Note>

## The shared payload

Each call accepts the customer's `mobileNumber`, your `metadataId`, a `sessionId`, and two signal objects:

```json theme={null}
{
  "mobileNumber": "+962791234567",
  "metadataId": "order-9921",
  "sessionId": "sess-abc123",
  "sdkSessionId": "b1f2c3d4-…",
  "device": {
    "platform": "android",
    "osVersion": "14",
    "model": "Pixel 8",
    "appVersion": "3.2.1",
    "sdkVersion": "1.1.0",
    "isRooted": false,
    "isEmulator": false,
    "vpnDetected": false,
    "proxyDetected": false,
    "appIntegrityStatus": "PASS",
    "deviceId": "device-hash-…"
  },
  "network": {
    "ipAddress": "5.10.20.30",
    "countryCode": "JO",
    "operator": "ZAIN_JO",
    "connectionType": "cellular"
  }
}
```

<Tip>
  Always include the `sdkSessionId` from the verification when you have it. It lets Shield and Detect compare the live request against the device context captured at verification time — powering the consistency signals below.
</Tip>

## Trust — a score for the decision

```bash theme={null}
curl -X POST https://service.authmatech.com/v1/api/trust/score \
  -H "X-API-KEY: YOUR_API_KEY" -H "X-CLIENT-ID: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d @signals.json
```

Returns a `trustScore` (0–100), a `confidence` band, a `recommendation` (`ALLOW`/`REVIEW`/`BLOCK`), and a high-level `breakdown`. Trust scores an identity from its **history with you**, so it's strongest on returning customers; drop `trustScore` into the rules you already run, or branch on `recommendation` directly.

See [`POST /v1/api/trust/score`](/api/overview).

## Shield — a decision for the action

```bash theme={null}
curl -X POST https://service.authmatech.com/v1/api/shield/assess \
  -H "X-API-KEY: YOUR_API_KEY" -H "X-CLIENT-ID: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d @signals.json
```

Returns a `decision` — `ALLOW`, `CHALLENGE`, `REVIEW`, or `BLOCK` — with a `riskScore`, `reasonCodes`, and consistency signals (`deviceConsistencyLevel`, `operatorConsistencyLevel`, `sdkVerified`). Wire the decision straight into your gate:

```javascript theme={null}
const { decision } = (await assess(signals)).data;
switch (decision) {
  case 'ALLOW':     return proceed();
  case 'CHALLENGE': return stepUp();      // e.g. re-verify or 2FA
  case 'REVIEW':    return queueForOps();
  case 'BLOCK':     return reject();
}
```

See [`POST /v1/api/shield/assess`](/api/overview).

## Detect — patterns over time

```bash theme={null}
curl -X POST https://service.authmatech.com/v1/api/detect/analyze \
  -H "X-API-KEY: YOUR_API_KEY" -H "X-CLIENT-ID: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d @signals.json
```

Returns a list of `anomalies` (categories like retry bursts, one device or installation linked to many numbers, IP concentration, and operator/country failure spikes), an `anomalyScore`, and a `recommendedAction` (`ALLOW`/`CHALLENGE`/`REVIEW`/`BLOCK`). Detect is ideal for fraud-ops dashboards and asynchronous review rather than blocking a single request.

See [`POST /v1/api/detect/analyze`](/api/overview).

## A common composition

```mermaid theme={null}
flowchart LR
    A[Verify identity] --> B{Sensitive action?}
    B -- yes --> C[Shield assess]
    C -->|ALLOW| D[Proceed]
    C -->|CHALLENGE| E[Step up]
    C -->|REVIEW/BLOCK| F[Hold / reject]
    A --> G[Detect analyze]
    G --> H[Fraud-ops dashboard]
```

Call **Shield inline** for the gate, and run **Detect continuously** to catch slow-building abuse your inline checks won't see in a single request.

<Note>
  Each product must be enabled for your account. A disabled product returns `400 Bad Request` with a message. Contact [connect@authmatech.com](mailto:connect@authmatech.com) to enable Trust, Shield, or Detect.
</Note>