Trust Signals API Reference

The Futurae Trust Signals API exposes the trust signals derived from observations that the Futurae Sensor SDKs collect on your users' devices and browsers. Each endpoint answers one risk question about a device: whether a browser is driven by a remote access tool, whether it has been seen before, whether two devices are physically near each other, or whether the user has traveled implausibly fast. Each returns a signal you can feed into your own risk engine.

The API is read-only. It retrieves signals computed from observations that the Sensor SDKs collect.

This document describes in detail how to format the HTTP Requests for calling the API endpoints, as well as the format of each individual HTTP request and response.

Current Trust Signals API Version: 1.0.0

Getting Started

Every request names your serviceId (the tenant) and an accountId (the end user). The optional unitId, verificationStatus and interactionId narrow the query; Remote Access Tool requires all three. See Identifiers.

Postman Sample Collection

To help you with integration, we provide a postman collection with a sample request for every Trust Signals API endpoint.

Once you import the collection into Postman, you will need to edit it and adjust the following collection variables:

Request Format

All endpoints are served from https://ts-signals-public.futurae.com under the /api/v1/ prefix and return application/json. Signal endpoints are grouped under /api/v1/signals/.

All parameters are supplied as query parameters, with the single exception of Get Remote Access Tool Signals (Batch), which takes a JSON array as its request body.

Headers

Request Authentication

Authorization header format:

Authorization: Bearer <token>

Requests are authenticated with an OAuth2 bearer token, obtained through the Client Credentials flow from the Futurae authorization server, auth.futurae.com.

Provisioned credentials

Requesting a signals token:

curl --location 'https://auth.futurae.com/oauth/v2/token?grant_type=client_credentials&scope=urn'\
'%3Azitadel%3Aiam%3Aorg%3Aproject%3Aid%3Ats-signals-public.futurae.com%3Aaud' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <base64(client_id:client_secret)>'

Futurae provisions two OAuth2 clients per integration, each with its own client_id and client_secret. Each client_id is a UUID, distinct from your serviceId.

This API accepts only a token issued to the retrieval client, with audience ts-signals-public.futurae.com and scope signals:read; any other token is rejected with 403.

The client_id and client_secret are passed to the token endpoint via HTTP Basic authentication. The resulting token is valid for all accounts within your tenant.

Token claims

Alongside the standard claims (iss, aud, exp, nbf, iat, jti), the token carries:

What your request must satisfy

A 401 means the token is missing, malformed, expired, carries an invalid signature, or uses a scheme other than Bearer. A 403 means the token is valid but the request is not permitted with it: the wrong scope or audience, or a serviceId that differs from the token claim. An identifier that breaks its documented constraints is rejected with 400.

Tenant Isolation

serviceId is the tenant boundary, and it is enforced on every request: the value you supply must equal the service_id claim on your access token. A mismatch is rejected with 403.

service_id is a signed token claim set by the Authorization Server, so the serviceId you send is always checked against the tenant the token was issued for.

Identifiers

Observations are stored under these identifiers and cannot be rekeyed afterwards, so settle your convention before production.

Matching

Each identifier you supply constrains which observations a query considers. An identifier you omit is left unconstrained. unitId, verificationStatus and interactionId are optional, except for Remote Access Tool, which requires all three.

The optional identifiers must be supplied in order: verificationStatus requires unitId, and interactionId requires verificationStatus. A request that breaks this order is rejected with 400. On the paired signals the same rule applies to each side.

Build interactionId from its most general part to its most specific, such as a session identifier followed by a page identifier, so that a shorter value selects a predictable group of interactions.

Paired signals

Latest Proximity, Historical Proximity and New Browser compare two sides. Every identifier except serviceId splits into a subject* / baseline* pair, and each side is narrowed independently by the rules above:

Response Format

A successful signal response:

Copy{
  "signalType": "active_call",
  "success": true,
  "result": { "onCall": true },
  "observationTime": "2026-04-22T14:15:20Z"
}

The same signal when it could not be computed:

Copy{
  "signalType": "active_call",
  "success": false,
  "reason": "insufficient_observations"
}

Every signal endpoint returns the same envelope: a signalType naming the signal, a success boolean, and, when successful, a result plus the timestamps of the observations it was computed from.

result is always a JSON object, for every signal.

A request that is well-formed and authorized but finds too few observations still returns 200, with success: false and a reason explaining why. Branch on success as well as on the HTTP status.

HTTP Response Codes

Signals

Get Latest Proximity Signal

Example request:

GET /api/v1/signals/latest-proximity?serviceId=f47ac10b-58cc-4372-a567-0e02b2c3d479&subjectAccountId=user-123&subjectUnitId=webApp&subjectVerificationStatus=verified&baselineUnitId=iosApp&baselineVerificationStatus=verified

GET /api/v1/signals/latest-proximity

Scores how likely it is that two devices are in the same place right now, by comparing their most recent observations. Typical use is to check that a user's phone is near the browser they are logging in from.

The confidence is accompanied by the supporting signals that produced it: overlapping IP addresses, matching Wi-Fi networks and shared nearby Bluetooth devices, so you can see what drove the result.

Query parameters

Response 200

Example response:

Copy{
  "signalType": "latest_proximity",
  "success": true,
  "result": {
    "proximityConfidence": 0.94,
    "supportingSignals": [
      { "type": "reportedIpOverlap",           "details": { "matched": true, "matchCount": null } },
      { "type": "wifiNetworkOverlap",          "details": { "matched": true, "matchCount": 2 } },
      { "type": "connectedWifiNetworkOverlap", "details": { "matched": true, "matchCount": null } },
      { "type": "connectedBleDeviceOverlap",   "details": { "matched": true, "matchCount": 1 } },
      { "type": "locationOverlap",             "details": { "matched": true, "matchCount": null } },
      { "type": "ingressIpCountryOverlap",     "details": { "matched": true, "matchCount": null } },
      { "type": "ingressIpOverlap",            "details": { "matched": true, "matchCount": null } }
    ]
  },
  "observationTimesByUnit": {
    "baselineUnitId": "2026-05-12T10:23:38.000Z",
    "subjectUnitId": "2026-05-12T10:23:41.000Z"
  }
}

Get Historical Proximity Signal

Example request:

GET /api/v1/signals/historical-proximity?serviceId=f47ac10b-58cc-4372-a567-0e02b2c3d479&subjectAccountId=user-123&subjectUnitId=androidApp&subjectVerificationStatus=verified&baselineUnitId=iosApp&baselineVerificationStatus=verified&windowStart=2026-05-12T08:00:00Z&windowEnd=2026-05-12T09:00:00Z

GET /api/v1/signals/historical-proximity

The time-range counterpart to Latest Proximity. Rather than comparing only the latest observation from each unit, it searches all observations in the window for the best matching pair.

Two independent best matches are returned: bestMatch over sensor observations, and bestIngressMatch over ingress-IP observations. Either may be null when no pair of that kind could be scored.

Query parameters

Response 200

Example response:

Copy{
  "signalType": "historical_proximity",
  "success": true,
  "result": {
    "bestMatch": {
      "proximityConfidence": 0.74,
      "supportingSignals": [
        { "type": "wifiNetworkOverlap", "details": { "matched": true, "matchCount": 2 } },
        { "type": "locationOverlap",    "details": { "matched": true, "matchCount": null } }
      ]
    },
    "bestIngressMatch": {
      "proximityConfidence": 0.66,
      "supportingSignals": [
        { "type": "ingressIpCountryOverlap", "details": { "matched": true,  "matchCount": null } },
        { "type": "ingressIpCityOverlap",    "details": { "matched": false, "matchCount": null } }
      ]
    }
  },
  "observationTimesByUnit": {
    "baselineUnitId": "2026-05-12T08:14:02.000Z",
    "subjectUnitId": "2026-05-12T08:57:11.000Z"
  }
}

Get New Browser Signal

Example request:

GET /api/v1/signals/new-browser?serviceId=f47ac10b-58cc-4372-a567-0e02b2c3d479&subjectAccountId=temp-preauth-9f2c&subjectUnitId=webApp&subjectVerificationStatus=unverified&baselineAccountId=user-123&baselineUnitId=webApp&baselineVerificationStatus=verified

GET /api/v1/signals/new-browser

Answers "have we seen this browser before?". It takes the latest browser fingerprint of the subject unit and checks whether it already appears in the baseline unit's observation history.

How the result is determined

1. If the subject side has no complete fingerprint observation, the signal returns success: false with reason: insufficient_observations.
2. If baselineAccountId is omitted, the latest subject fingerprint is compared against the subject side's own earlier observations in the window, excluding the cooldownSeconds period.
3. Otherwise the baseline side's history in the window is checked, excluding the cooldownSeconds period. If it is empty, known is false.
4. Otherwise the latest subject fingerprint is compared against every baseline observation in that history. known is true if any match.

Query parameters

Matching cooldown

Only fingerprints older than the cooldown cutoff count toward a known: true result. This matters in two ways:

• Ignoring a session's own resubmissions. The SDK rewrites the fingerprint repeatedly during a session. Without a cooldown a brand-new device could match its own recent submissions and wrongly come back as known. This matters only when the subject and baseline sides cover the same unit.
• Giving recent sessions time to be trusted. A session from moments ago may not yet be confirmed legitimate. The cooldown holds it back from counting as trusted history.

Response 200

Example response:

Copy{
  "signalType": "new_browser",
  "success": true,
  "result": { "known": false },
  "mismatchedFields": ["browser_version"],
  "unitId": "webApp",
  "verificationStatus": "unverified",
  "interactionId": "session-9f2c-login",
  "observationTime": "2026-05-12T10:23:41.000Z"
}

Get Geolocation Signal

Example request:

GET /api/v1/signals/geolocation?serviceId=f47ac10b-58cc-4372-a567-0e02b2c3d479&accountId=user-123&unitId=iosApp&verificationStatus=verified

GET /api/v1/signals/geolocation

Returns the best available location estimate for a unit, drawing from GPS (mobile only) and ingress IP geolocation. Each source is returned as a separate datapoint so you can apply your own resolution and confidence logic.

Query parameters

Response 200

Example response:

Copy{
  "signalType": "geolocation",
  "success": true,
  "result": {
    "datapoints": [
      { "name": "geo", "observationTime": "2026-04-22T14:15:20Z", "valueType": "geo", "lat": 47.4979, "lon": 19.0402,
        "unitId": "iosApp", "verificationStatus": "verified", "interactionId": "installation-4b1e" },
      { "name": "ingress_ip_geo", "observationTime": "2026-04-22T14:15:20Z", "valueType": "geo", "lat": 47.49, "lon": 19.04,
        "unitId": "iosApp", "verificationStatus": "verified", "interactionId": "installation-4b1e" },
      { "name": "ingress_ip_city", "observationTime": "2026-04-22T14:15:20Z", "valueType": "string", "value": "Budapest",
        "unitId": "iosApp", "verificationStatus": "verified", "interactionId": "installation-4b1e" },
      { "name": "ingress_ip_country", "observationTime": "2026-04-22T14:15:20Z", "valueType": "string", "value": "HU",
        "unitId": "iosApp", "verificationStatus": "verified", "interactionId": "installation-4b1e" }
    ]
  },
  "observationTime": "2026-04-22T14:15:20Z"
}

Datapoints that can appear, each present only when data exists for it:

Get Geovelocity Signal

Example request:

GET /api/v1/signals/geovelocity?serviceId=f47ac10b-58cc-4372-a567-0e02b2c3d479&accountId=user-123&unitId=iosApp&verificationStatus=verified&windowStart=2026-05-12T08:00:00Z&windowEnd=2026-05-12T10:00:00Z

GET /api/v1/signals/geovelocity

Flags physically impossible travel of the user's mobile device: it computes the maximum speed implied by pairs of location observations in the window and compares it against a plausibility threshold.

Query parameters

Response 200

Example response:

Copy{
  "signalType": "geovelocity",
  "success": true,
  "result": {
    "anomaly": true,
    "maxSpeedKmh": 1520.4,
    "sources": [
      {
        "locationSource": "gps",
        "evaluated": true,
        "anomaly": true,
        "maxSpeedKmh": 1520.4,
        "thresholdKmh": 900,
        "evaluatedPairCount": 1,
        "fastestPair": {
          "fromObservationTime": "2026-04-22T09:15:20Z",
          "toObservationTime": "2026-04-22T10:05:11Z",
          "fromUnitId": "iosApp",
          "fromVerificationStatus": "verified",
          "fromInteractionId": "installation-4b1e",
          "toUnitId": "iosApp",
          "toVerificationStatus": "verified",
          "toInteractionId": "installation-4b1e",
          "distanceKm": 1263.1,
          "elapsedSeconds": 2991,
          "speedKmh": 1520.4
        }
      }
    ]
  },
  "observationTime": "2026-04-22T10:05:11Z"
}

Get Active Call Signal

Example request:

GET /api/v1/signals/active-call?serviceId=f47ac10b-58cc-4372-a567-0e02b2c3d479&accountId=user-123&unitId=iosApp&verificationStatus=verified

GET /api/v1/signals/active-call

Reports whether the device was on a phone call at its most recent observation. This is a signal against social-engineering attacks, where a victim is on the phone with the attacker while authorizing a transaction.

Query parameters

Response 200

Example response:

Copy{
  "signalType": "active_call",
  "success": true,
  "result": { "onCall": true },
  "unitId": "iosApp",
  "verificationStatus": "verified",
  "interactionId": "installation-4b1e",
  "observationTime": "2026-05-12T10:22:58.000Z"
}

Get Remote Access Tool Signal

Example request:

GET /api/v1/signals/remote-access-tool?serviceId=f47ac10b-58cc-4372-a567-0e02b2c3d479&accountId=user-123&unitId=webApp&verificationStatus=verified&interactionId=session-9f2c-payment

GET /api/v1/signals/remote-access-tool

Scores the likelihood that a browser is being operated via remote desktop software rather than directly by a human, which is the signature of a remote-access scam. The classifier runs on browser fingerprint characteristics, keyboard dynamics and mouse movement patterns.

Scoring prerequisites

All four must hold, or the signal returns success: false with the reason shown:

Baseline anchoring

The classifier compares each session against a per-user, per-platform baseline built from that user's own past sessions, as they stood at the moment the scored session took place. A session queried long after it occurred is scored against the baseline it had at the time.

Query parameters

Response 200

Example response:

Copy{
  "signalType": "remote_access_tool",
  "success": true,
  "result": {
    "anomaly": true,
    "anomalyConfidence": 0.82
  },
  "unitId": "webApp",
  "verificationStatus": "verified",
  "interactionId": "session-9f2c-payment",
  "observationTime": "2026-04-22T14:15:20Z"
}

Get Remote Access Tool Signals (Batch)

Example request:

POST /api/v1/signals/remote-access-tool
Content-Type: application/json

Example request body:

Copy[
  { "serviceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "accountId": "user-123", "unitId": "webApp", "verificationStatus": "verified", "interactionId": "session-9f2c-payment" },
  { "serviceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "accountId": "user-456", "unitId": "webApp", "verificationStatus": "unverified", "interactionId": "session-71ad-login" }
]

POST /api/v1/signals/remote-access-tool

Batch variant of Get Remote Access Tool Signal. Scores many sessions in one call, using the same logic as the single-item endpoint.

Headers

Request body

A JSON array of 1–100 objects. An empty or oversized batch is rejected with a bare 400.

Fixed behavior

Every item in a batch is scored identically:

Results are returned in the same order as the request. A single request can mix sessions the token is and isn't authorized for, so authorization failures are reported per item with reason: forbidden rather than as a top-level 403.

Response 200

Example response:

Copy{
  "signalType": "remote_access_tool",
  "results": [
    {
      "accountId": "user-123",
      "unitId": "webApp",
      "verificationStatus": "verified",
      "interactionId": "session-9f2c-payment",
      "success": false,
      "reason": "insufficient_observations"
    },
    {
      "accountId": "user-456",
      "unitId": "webApp",
      "verificationStatus": "unverified",
      "interactionId": "session-71ad-login",
      "success": true,
      "result": { "anomaly": false, "anomalyConfidence": 0.04 },
      "observationTime": "2026-04-22T14:15:20Z"
    }
  ]
}

Response 400

Returned without the standard envelope for a Content-Type other than application/json, or a batch outside the 1–100 range.

Response 401

Authorization information is missing, or the token is invalid. The batch endpoint authenticates the same way as the single-item endpoint.

Resources

Verification Status

verificationStatus records the end user's authentication state, decoupled from identity. Futurae never verifies it: on a query it is a filter over which observations are considered, optional except for Remote Access Tool. See Matching.

Failure Reasons

When a signal returns success: false, reason carries a machine-readable explanation.

The single-item endpoints report the cases behind forbidden and internalError as HTTP errors instead.

Supporting Signals

The two proximity signals report the individual signals that contributed to a result. Each entry has a type and a details object of uniform shape:

The optional supportingSignal query parameter on both proximity endpoints restricts computation to a single type.

Sensor-derived

Ingress-IP-derived

Derived from the IP observed at Futurae's network edge, rather than reported by the SDK.

Geovelocity Source

One entry per location source evaluated by Get Geovelocity Signal.

Fastest pair

Datapoints

A datapoint is one stored observation of one measurement. Every datapoint carries the common fields below, plus a value whose shape is determined by valueType.

Value by type

Each valueType adds the fields below to the common ones.