Authentifizierung
API-Schlüssel
Guardian verwendet einen sp_live_*-API-Schlüssel, der vom Surt-Team bereitgestellt wird. Nur dein Backend hält diesen Schlüssel. Dein Backend fordert damit JWTs an, und der Schlüssel gelangt niemals an den Client (mobile App oder Web). Der Client hält nur die JWTs, die ihm dein Backend übergibt.
API-Schlüssel beschaffen
- Kontaktiere das Surt-Team, um die Anmeldedaten deiner Organisation zu erhalten
- Melde dich in deinem Surt-Dashboard an
- Navigiere zu Einstellungen → Entwickler
- Kopiere deinen API-Schlüssel und speichere ihn als serverseitiges Geheimnis
So funktioniert die Authentifizierung
- Dein Backend hält den
sp_live_*-API-Schlüssel (serverseitiges Geheimnis). - Vor dem Aufruf von
verify()fordert deine App einen Token von deinem eigenen Backend an. - Dein Backend ruft
POST /geolocation/preflightmitAuthorization: Bearer <api key>und dem Transaktionskontext auf und gibt danndata.token(das JWT) an die App zurück. - Deine App übergibt das JWT an
verify(jwt).
Hinweise:
- Ein JWT pro Transaktion. Fordere für jede Transaktion ein neues JWT an. Ein JWT läuft 30 Minuten nach der Ausstellung ab.
- Das
collect()-JWT ist optional. Übergib es, damit die öffentliche IP des Geräts in das Payload aufgelöst wird und die Attestierungseinstellungen deiner Organisation angewendet werden. Siehe Collect (Server-zu-Server).
Preflight-Anfrage
POST https://api.surt.com/geolocation/preflight
Authorization: Bearer sp_live_xxx
Content-Type: application/json
{
"customer_id": "user_abc123",
"transaction_type": "login",
"transaction_name": "User Login",
"name": "John Doe",
"email": "john@example.com",
"phone": "+15555550100"
}
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
customer_id | string | Nein | Deine Benutzerkennung. Lass das Feld weg oder sende einen leeren String für eine anonyme Transaktion, zum Beispiel vor dem Login. |
transaction_type | string | Ja | login, sign_up, deposit, withdrawal oder ein eigener String mit bis zu 64 Zeichen. Siehe Transaktionstypen. |
transaction_name | string | Nein | Menschenlesbare Bezeichnung |
name | string | Nein | Der Name des Kunden |
email | string | Nein | Die E-Mail-Adresse des Kunden. Ein leerer String gilt als nicht vorhanden. Eine ungültige Adresse liefert 400. |
phone | string | Nein | Die Telefonnummer des Kunden. Ein leerer String gilt als nicht vorhanden. Eine Nummer, die sich nicht parsen lässt, liefert 400. |
install_id | string | Nein | Nur Guardian Web. Siehe Web install id. |
Antwort:
{
"data": {
"token": "<jwt>"
}
}
Der Kunden- und Transaktionskontext lebt in den JWT-Claims (von deinem Backend zur Preflight-Zeit gesetzt), sodass der Client niemals eine Kunden-ID oder einen Transaktionstyp übergibt.
data.token läuft 30 Minuten nach der Ausstellung ab.
| Code | Wann |
|---|---|
400 | Fehlerhaftes JSON, ein fehlender transaction_type oder ein ungültiger Wert für email, phone oder transaction_type |
401 | Die Anfrage hat keinen Authorization-Header |
403 | Der API-Schlüssel ist ungültig oder inaktiv, oder Guardian ist für deine Organisation nicht aktiviert |
503 | Vorübergehender Fehler. Wiederhole die Anfrage. |
Die Antwort-Bodys findest du unter Fehlercodes.
Web install id (v0.5.0)
Guardian Web v0.5.0 ergänzt Preflight um eine optionale install_id, damit die
Geräteidentität eines Browsers in einem First-Party-Cookie gespeichert werden kann und eine
Speicherbereinigung übersteht. Sie gilt nur für @surtai/guardian-web; die nativen SDKs ignorieren sie.
-
Anfrage - sende die
install_idmit, die dein Backend aus seinem First-Party-Cookie gelesen hat (lass sie beim ersten Besuch weg):{
"customer_id": "user_abc123",
"transaction_type": "login",
"install_id": "<id from your first-party cookie, or omit>"
} -
Antwort - Preflight gibt diese id zurück (oder erzeugt eine neue) und bettet sie zusätzlich als JWT-Claim ein. Das Web-SDK liest den Claim aus dem
geolocationJwt, das du ancollect()übergibst, und nur dann, wenn der Browser keine gespeicherte install id hat. Setze dein First-Party-Cookie damit neu:{
"data": {
"token": "<jwt, now carrying an install_id claim>",
"install_id": "<id to store in your first-party cookie>"
}
}
Das ist optional - Web funktioniert auch ohne. Den vollständigen Ablauf und das etwa fünfzeilige Cookie-Relay findest du unter Guardian Web → Migration v0.4 → v0.5.
Paketzugriffstoken
Das SDK selbst wird als privates Paket vertrieben. Du erhältst außerdem Zugriffstoken für die Paketinstallation. Diese sind getrennt vom oben genannten API-Schlüssel:
| Plattform | Token-Typ | Konfigurationsort |
|---|---|---|
| React Native | npm-Token | .npmrc im Projektstamm |
| iOS | GitHub-Token | ~/.netrc |
| Android | GitHub-Token | gradle.properties |
Details findest du in den plattformspezifischen Installationsleitfäden:
Basis-URL
Das SDK spricht immer die Produktion unter https://api.surt.com an.
Bewahre deinen sp_live_*-API-Schlüssel jederzeit serverseitig auf. Er dient ausschließlich dazu, JWTs zu erzeugen. Bette ihn niemals in App- oder Web-Client-Code ein. Der Client hält nur JWTs, die nach 30 Minuten ablaufen.