Skip to main content
Version: Guardian v0.5.3

Collect (Server-to-Server)

v0.3.0+

Two Verification Paths​

Guardian SDK offers two ways to verify devices. Choose based on your architecture:

verify()collect()
Who calls SurtThe SDK (from the device)Your backend (server-to-server)
JWT requirementRequired, a new one for each callOptional
Your backend involvedNoYes
ResponseVerificationResult (allowed/denied)CollectResult (encrypted payload)
Best forSimple integration, frontend-driven decisionsBackend-driven decisions, custom logic, audit requirements

verify() flow​

App → fetch fresh JWT from your backend → SDK.verify(jwt) → Surt backend → risk decision → App

The SDK calls Surt directly and returns allowed: true/false. Your app acts on the decision immediately. Request a new JWT for each call.

collect() flow​

App → SDK.collect() → encrypted payload → App → Your backend → Surt /evaluate → Your backend → App

The SDK collects device data and encrypts it on the device. collect() does not send the device payload to Surt. Your backend sends the payload to Surt's evaluate endpoint, receives the risk assessment, and decides what to return to your app.

When to Use collect()​

  • Your backend needs the risk data before responding to the client
  • You want to combine device risk with your own business logic server-side
  • You need full control over what the client sees

Usage​

1. Collect on the device​

import { useGuardian } from '@surtai/guardian-rn';

function PaymentScreen() {
const { collect } = useGuardian();

const handlePayment = async () => {
// The JWT is optional for collect(). Pass collect(jwt) to resolve the
// device's public IP into the payload and to apply your organization's
// attestation settings.
const { payload } = await collect();

// Send payload to YOUR backend
const response = await fetch('https://your-api.com/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
payload,
amount: 500,
currency: 'USD',
}),
});

const result = await response.json();
// Your backend already made the risk decision
};
}

The JWT is optional for collect(). When you pass one, the SDK does two things with it:

  • It calls GET /geolocation/client-ip and adds the device's public IP to the payload.
  • It applies your organization's attestation settings: how often a device attests and, on Android, your own Play Integrity project. See Device attestation setup.

Without a JWT, the payload carries no resolved public IP and the SDK attests on every call with the default settings. Request a new JWT for each transaction. A JWT expires 30 minutes after it is issued.

2. Call Surt from your backend​

Your backend receives the encrypted payload from the app, then calls Surt's evaluate endpoint:

POST https://api.surt.com/geolocation/transactions/evaluate
Content-Type: application/json
Authorization: Bearer YOUR_SURT_API_KEY
{
"customer_id": "user_123",
"transaction_type": "withdrawal",
"transaction_name": "User Payment",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+15555550100",
"event_id": "withdrawal-8841",
"payload": {
"type": "encrypted",
"data": "<payload from SDK>"
},
"config": {
"response": {
"address": { "type": "include" }
}
}
}

Request fields​

FieldTypeRequiredDescription
customer_idstringNoYour user identifier. Omit it, or send an empty string, for an anonymous transaction, for example before login.
transaction_typestringYeslogin, sign_up, deposit, withdrawal, or a custom string of up to 64 characters. See Transaction Types.
transaction_namestringNoHuman-readable label
namestringNoThe customer's name
emailstringNoThe customer's email. An empty string counts as absent. An invalid address returns 400.
phonestringNoThe customer's phone number. An empty string counts as absent. A number that cannot be parsed returns 400.
event_idstringNoYour ID for this event, unique within your organization. 1 to 128 characters: letters, digits, ., _, : and -. See Idempotency.
payload.typestringYesAlways "encrypted"
payload.datastringYesThe encrypted payload from collect()
config.response.addressobjectNo{ "type": "include" } to get the full address, omitted by default

Idempotency​

Send an event_id to make the request safe to retry. Surt evaluates each event_id once.

  • A repeated request with the same event_id returns 200 with the response of the first evaluation. Surt does not score the event again.
  • A repeated request that arrives while the first one is still being evaluated returns 409. Retry after a short wait.
  • If the first evaluation fails, Surt releases the event_id and a retry is evaluated as a new request.

Surt keeps an event_id for at least 24 hours. Without an event_id, every request creates a new transaction.

Config​

The config object controls what optional data is included in the response.

{
"config": {
"response": {
"address": { "type": "include" }
}
}
}
FieldValuesDefaultDescription
config.response.address.type"include" or "omit""omit"Whether to include the full reverse-geocoded address (street, city, state, country, postal code) in the response. Requires GPS data in the payload.

When address is omitted (default), the response has no address field, even if location data was collected. Set it to "include" if your backend needs the physical address for compliance, fraud review, or display.

Authentication​

Use your Surt API key in the Authorization header as a Bearer token. This is a server-to-server call. The API key never reaches the device.

3. Handle the response​

The evaluate endpoint returns the transaction with its risk level and decision. The example shows the fields to build on. The transaction object carries more fields than these, so ignore any field that is not in the table below.

With config.response.address.type: "include"​

{
"status_code": 200,
"message": "Transaction evaluated successfully",
"data": {
"transaction": {
"transaction_id": "1775514112-f2e3034b891e4c6a9d0b7a1c5e8f20",
"event_id": "withdrawal-8841",
"created_at": "2026-04-06T22:21:52Z",
"customer_id": "user_123",
"transaction_type": "withdrawal",
"transaction_name": "User Payment",
"risk_level": "low",
"status": "completed",
"details": {
"risk_level": "low",
"address": {
"street": "Main St",
"city": "San Francisco",
"state": "California",
"country": "United States",
"postal_code": "94103",
"formatted_address": "123 Main St, San Francisco, CA 94103, USA"
}
},
"result": {
"status": "accepted",
"review": false
},
"network_threat": {
"status": "clear"
},
"device": {
"device_id": "5b1f0c1e-8a43-5c0e-9d55-2f6c1d7a9b10",
"manufacturer": "Apple",
"model": "iPhone 15",
"os_version": "18.0"
}
}
}
}

With config.response.address.type: "omit" (default)​

Same response, but details has no address field:

"details": {
"risk_level": "low"
}

Response fields​

All fields are inside data.transaction.

FieldTypePresentDescription
transaction_idstringAlwaysSurt's ID for the transaction
event_idstringWhen you sent oneThe event_id from the request
created_atstringAlwaysCreation time, ISO 8601 in UTC
customer_idstringWhen you sent oneAbsent for an anonymous transaction
transaction_typestringAlwaysThe type from the request
transaction_namestringWhen you sent oneThe label from the request
risk_levelstringAlwayslow, medium, or high. See Risk Levels.
statusstringAlwayscompleted, or failed when Surt could not process the transaction
details.risk_levelstringWhen status is completedSame value as risk_level
details.addressobjectWhen status is completed, the request asked for it, and an address was resolvedformatted_address (string, always), plus street, city, state, country and postal_code (strings, each present when known)
details.errorstringWhen status is failedWhy processing failed. risk_level is high in this case.
result.statusstringAlwaysaccepted or rejected. This is the decision.
result.reviewbooleanAlwaystrue when the transaction is flagged for manual review
result.detailsobjectWhen result.status is rejectedWhy the transaction was rejected. type is scenarios (with a scenarios array of { scenario_id, scenario_name }), blacklisted, blocked (with kind.type set to deposits or withdrawals), or node_ids.
network_threat.statusstringAlwaysnot_analyzed, clear, or detected
network_threat.threatsstring[]When network_threat.status is detectedAny of vpn, proxy, tor
deviceobjectAlwaysdevice_id (string, always), plus manufacturer, model and os_version (strings, each present when known)

risk_level and result.status are independent: a high risk transaction can be accepted. Decide on result.status, and use risk_level, result.review, network_threat, and details.address for your own rules before responding to the client.

Errors​

CodeWhen
400Malformed JSON, a missing required field, an invalid email, phone, event_id or transaction_type, or a payload.data that Surt cannot decrypt
401The request has no Authorization header
403The API key is invalid or inactive, or Guardian is not enabled for your organization
409Another request with the same event_id is still being evaluated. Retry after a short wait.
503Temporary failure. Retry the request.

See Error Codes for the response bodies.

Location Override​

Same as verify(), you can override location collection per call:

// Collect with location
const { payload } = await collect(jwt, { collectLocation: true });

// Collect without location and without a JWT
const { payload } = await collect(undefined, { collectLocation: false });

On Android, collectLocation: true on a call has an effect only when collectLocation was also true at initialization. On iOS it enables location for that call.

CollectResult​

interface CollectResult {
/** Base64-encoded encrypted payload. Pass as payload.data in the evaluate request. */
payload: string;
}

The payload is encrypted and can only be decrypted by Surt's backend. It contains the device fingerprint, device integrity signals, security signals, and optionally location.

The collect() result also includes an optional diagnostics object that describes what the SDK observed on the device. React Native returns it from v0.5.2. You can ignore it.

const { payload, diagnostics } = await collect();
// diagnostics?.location: 'collected' | 'denied' | 'unavailable' | 'timeout' | 'not_requested' | 'error'
// diagnostics?.attestation: 'collected' | 'unavailable' | 'failed' | 'not_supported' | 'not_requested'
// diagnostics?.networkIntel: 'collected' | 'unavailable' | 'not_requested'
// diagnostics?.warnings: { code, signal, detail? }[]
// diagnostics?.timings: { [phase]: ms } (Android; iOS from v0.5.3)

See Error Codes → Result diagnostics.

Backend Example​

app.post('/verify-device', async (req, res) => {
const { payload, userId } = req.body;

const surtResponse = await fetch(
'https://api.surt.com/geolocation/transactions/evaluate',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.SURT_API_KEY}`,
},
body: JSON.stringify({
customer_id: userId,
transaction_type: 'login',
payload: { type: 'encrypted', data: payload },
config: { response: { address: { type: 'include' } } },
}),
}
);

if (!surtResponse.ok) {
return res.status(502).json({ allowed: false });
}

const { data } = await surtResponse.json();
const risk = data.transaction.risk_level;
const accepted = data.transaction.result.status === 'accepted';

res.json({ allowed: accepted, risk });
});