Zum Hauptinhalt springen
Version: Guardian v0.5.3

Collect (Server-zu-Server)

v0.3.0+

Zwei Verifizierungswege​

Das Guardian SDK bietet zwei Wege, Geräte zu verifizieren. Wählen Sie nach Ihrer Architektur:

verify()collect()
Wer Surt aufruftDas SDK (vom Gerät aus)Ihr Backend (Server-zu-Server)
JWT-AnforderungErforderlich, ein neues für jeden AufrufOptional
Ihr Backend beteiligtNeinJa
AntwortVerificationResult (erlaubt/abgelehnt)CollectResult (verschlüsseltes Payload)
Am besten fürEinfache Integration, Frontend-gesteuerte EntscheidungenBackend-gesteuerte Entscheidungen, eigene Logik, Audit-Anforderungen

Ablauf von verify()​

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

Das SDK ruft Surt direkt auf und gibt allowed: true/false zurück. Ihre App handelt sofort nach der Entscheidung. Fordern Sie für jeden Aufruf ein neues JWT an.

Ablauf von collect()​

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

Das SDK erfasst Gerätedaten und verschlüsselt sie auf dem Gerät. collect() sendet das Geräte-Payload nicht an Surt. Ihr Backend sendet das Payload an Surts Evaluate-Endpoint, erhält die Risikobewertung und entscheidet, was es an Ihre App zurückgibt.

Wann collect() verwenden​

  • Ihr Backend benötigt die Risikodaten, bevor es dem Client antwortet
  • Sie möchten das Geräterisiko serverseitig mit Ihrer eigenen Geschäftslogik kombinieren
  • Sie benötigen die volle Kontrolle darüber, was der Client sieht

Verwendung​

1. Auf dem Gerät sammeln​

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
};
}

Das JWT ist für collect() optional. Wenn Sie eines übergeben, nutzt das SDK es für zwei Dinge:

  • Es ruft GET /geolocation/client-ip auf und fügt die öffentliche IP des Geräts zum Payload hinzu.
  • Es wendet die Attestierungseinstellungen Ihrer Organisation an: wie oft ein Gerät attestiert und, unter Android, Ihr eigenes Play-Integrity-Projekt. Siehe Einrichtung der Geräte-Attestierung.

Ohne JWT enthält das Payload keine aufgelöste öffentliche IP, und das SDK attestiert bei jedem Aufruf mit den Standardeinstellungen. Fordern Sie für jede Transaktion ein neues JWT an. Ein JWT läuft 30 Minuten nach der Ausstellung ab.

2. Surt von Ihrem Backend aufrufen​

Ihr Backend erhält das verschlüsselte Payload von der App und ruft dann Surts Evaluate-Endpoint auf:

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" }
}
}
}

Anforderungsfelder​

FeldTypErforderlichBeschreibung
customer_idstringNeinIhre Benutzerkennung. Lassen Sie das Feld weg oder senden Sie einen leeren String für eine anonyme Transaktion, zum Beispiel vor dem Login.
transaction_typestringJalogin, sign_up, deposit, withdrawal oder ein eigener String mit bis zu 64 Zeichen. Siehe Transaktionstypen.
transaction_namestringNeinMenschenlesbare Bezeichnung
namestringNeinDer Name des Kunden
emailstringNeinDie E-Mail-Adresse des Kunden. Ein leerer String gilt als nicht vorhanden. Eine ungültige Adresse liefert 400.
phonestringNeinDie Telefonnummer des Kunden. Ein leerer String gilt als nicht vorhanden. Eine Nummer, die sich nicht parsen lässt, liefert 400.
event_idstringNeinIhre ID für dieses Ereignis, eindeutig innerhalb Ihrer Organisation. 1 bis 128 Zeichen: Buchstaben, Ziffern, ., _, : und -. Siehe Idempotenz.
payload.typestringJaImmer "encrypted"
payload.datastringJaDas verschlüsselte Payload von collect()
config.response.addressobjectNein{ "type": "include" }, um die vollständige Adresse zu erhalten, standardmäßig weggelassen

Idempotenz​

Senden Sie eine event_id, damit die Anfrage gefahrlos wiederholt werden kann. Surt wertet jede event_id einmal aus.

  • Eine wiederholte Anfrage mit derselben event_id liefert 200 mit der Antwort der ersten Auswertung. Surt bewertet das Ereignis nicht erneut.
  • Eine wiederholte Anfrage, die eintrifft, während die erste noch ausgewertet wird, liefert 409. Wiederholen Sie die Anfrage nach kurzer Wartezeit.
  • Schlägt die erste Auswertung fehl, gibt Surt die event_id frei, und eine Wiederholung wird als neue Anfrage ausgewertet.

Surt bewahrt eine event_id mindestens 24 Stunden auf. Ohne event_id erzeugt jede Anfrage eine neue Transaktion.

Config​

Das config-Objekt steuert, welche optionalen Daten in der Antwort enthalten sind.

{
"config": {
"response": {
"address": { "type": "include" }
}
}
}
FeldWerteStandardBeschreibung
config.response.address.type"include" oder "omit""omit"Ob die vollständige, per Reverse-Geocoding ermittelte Adresse (Straße, Stadt, Bundesland, Land, Postleitzahl) in der Antwort enthalten sein soll. Erfordert GPS-Daten im Payload.

Wenn address weggelassen wird (Standard), hat die Antwort kein address-Feld, auch wenn Standortdaten erfasst wurden. Setzen Sie den Wert auf "include", wenn Ihr Backend die physische Adresse für Compliance, Betrugsprüfung oder Anzeige benötigt.

Authentifizierung​

Verwenden Sie Ihren Surt-API-Schlüssel im Authorization-Header als Bearer-Token. Dies ist ein Server-zu-Server-Aufruf. Der API-Schlüssel erreicht das Gerät nie.

3. Antwort verarbeiten​

Der Evaluate-Endpoint gibt die Transaktion mit ihrer Risikostufe und Entscheidung zurück. Das Beispiel zeigt die Felder, auf die Sie aufbauen können. Das transaction-Objekt enthält mehr Felder als diese, ignorieren Sie daher jedes Feld, das nicht in der Tabelle unten steht.

Mit 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"
}
}
}
}

Mit config.response.address.type: "omit" (Standard)​

Dieselbe Antwort, aber details hat kein address-Feld:

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

Antwortfelder​

Alle Felder liegen in data.transaction.

FeldTypVorhandenBeschreibung
transaction_idstringImmerSurts ID für die Transaktion
event_idstringWenn Sie eine gesendet habenDie event_id aus der Anfrage
created_atstringImmerErstellungszeit, ISO 8601 in UTC
customer_idstringWenn Sie eine gesendet habenFehlt bei einer anonymen Transaktion
transaction_typestringImmerDer Typ aus der Anfrage
transaction_namestringWenn Sie einen gesendet habenDie Bezeichnung aus der Anfrage
risk_levelstringImmerlow, medium oder high. Siehe Risikostufen.
statusstringImmercompleted, oder failed, wenn Surt die Transaktion nicht verarbeiten konnte
details.risk_levelstringWenn status completed istDerselbe Wert wie risk_level
details.addressobjectWenn status completed ist, die Anfrage sie angefordert hat und eine Adresse ermittelt wurdeformatted_address (string, immer), dazu street, city, state, country und postal_code (strings, jeweils vorhanden, wenn bekannt)
details.errorstringWenn status failed istWarum die Verarbeitung fehlgeschlagen ist. risk_level ist in diesem Fall high.
result.statusstringImmeraccepted oder rejected. Das ist die Entscheidung.
result.reviewbooleanImmertrue, wenn die Transaktion zur manuellen Prüfung markiert ist
result.detailsobjectWenn result.status rejected istWarum die Transaktion abgelehnt wurde. type ist scenarios (mit einem scenarios-Array von { scenario_id, scenario_name }), blacklisted, blocked (mit kind.type gleich deposits oder withdrawals) oder node_ids.
network_threat.statusstringImmernot_analyzed, clear oder detected
network_threat.threatsstring[]Wenn network_threat.status detected istBeliebige aus vpn, proxy, tor
deviceobjectImmerdevice_id (string, immer), dazu manufacturer, model und os_version (strings, jeweils vorhanden, wenn bekannt)

risk_level und result.status sind unabhängig voneinander: Eine Transaktion mit Risiko high kann accepted sein. Entscheiden Sie anhand von result.status, und nutzen Sie risk_level, result.review, network_threat und details.address für Ihre eigenen Regeln, bevor Sie dem Client antworten.

Fehler​

CodeWann
400Fehlerhaftes JSON, ein fehlendes Pflichtfeld, ein ungültiger Wert für email, phone, event_id oder transaction_type oder ein payload.data, das Surt nicht entschlüsseln kann
401Die Anfrage hat keinen Authorization-Header
403Der API-Schlüssel ist ungültig oder inaktiv, oder Guardian ist für Ihre Organisation nicht aktiviert
409Eine andere Anfrage mit derselben event_id wird noch ausgewertet. Wiederholen Sie die Anfrage nach kurzer Wartezeit.
503Vorübergehender Fehler. Wiederholen Sie die Anfrage.

Die Antwort-Bodys finden Sie unter Fehlercodes.

Standortüberschreibung​

Wie bei verify() können Sie die Standorterfassung pro Aufruf überschreiben:

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

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

Unter Android wirkt collectLocation: true bei einem Aufruf nur, wenn collectLocation auch bei der Initialisierung true war. Unter iOS aktiviert es den Standort für diesen Aufruf.

CollectResult​

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

Das Payload ist verschlüsselt und kann nur von Surts Backend entschlüsselt werden. Es enthält den Gerätefingerabdruck, Geräteintegritätssignale, Sicherheitssignale und optional den Standort.

Das collect()-Ergebnis enthält außerdem ein optionales diagnostics-Objekt, das beschreibt, was das SDK auf dem Gerät beobachtet hat. React Native gibt es ab v0.5.2 zurück. Sie können es ignorieren.

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)

Siehe Fehlercodes → Ergebnis-Diagnose.

Backend-Beispiel​

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 });
});