Skip to main content
Version: Guardian v0.5.3

Authentication

API Key​

Guardian uses an sp_live_* API key provided by the Surt team. Only your backend holds that key. Your backend uses it to request JWTs, and it never ships to the client (mobile app or web). The client only holds the JWTs your backend hands it.

Getting Your API Key​

  1. Contact the Surt team to get your organization credentials
  2. Log in to your Surt Dashboard
  3. Navigate to Settings → Developer
  4. Copy your API key and store it as a server-side secret

How auth works​

  1. Your backend holds the sp_live_* API key (server-side secret).
  2. Before calling verify(), your app requests a token from your own backend.
  3. Your backend calls POST /geolocation/preflight with Authorization: Bearer <api key> and the transaction context, then returns data.token (the JWT) to the app.
  4. Your app passes the JWT to verify(jwt).

Notes:

  • One JWT per transaction. Request a new JWT for each transaction. A JWT expires 30 minutes after it is issued.
  • The collect() JWT is optional. Pass it to resolve the device's public IP into the payload and to apply your organization's attestation settings. See Collect (Server-to-Server).

Preflight request​

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"
}
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.
install_idstringNoGuardian Web only. See Web install id.

Response:

{
"data": {
"token": "<jwt>"
}
}

The customer and transaction context live in the JWT claims (set by your backend at preflight time), so the client never passes a customer id or transaction type.

data.token expires 30 minutes after it is issued.

CodeWhen
400Malformed JSON, a missing transaction_type, or an invalid email, phone or transaction_type
401The request has no Authorization header
403The API key is invalid or inactive, or Guardian is not enabled for your organization
503Temporary failure. Retry the request.

See Error Codes for the response bodies.

Web install id (v0.5.0)​

Guardian Web v0.5.0 adds an optional install_id to preflight so a browser's device identity can be persisted in a first-party cookie and survive storage eviction. It applies only to @surtai/guardian-web; the native SDKs ignore it.

  • Request - include the install_id your backend read from its first-party cookie (omit it on the first visit):

    {
    "customer_id": "user_abc123",
    "transaction_type": "login",
    "install_id": "<id from your first-party cookie, or omit>"
    }
  • Response - preflight echoes that id (or mints a fresh one) and also embeds it as a JWT claim. The web SDK reads the claim from the geolocationJwt you pass to collect(), and only when the browser has no stored install id. Re-set your first-party cookie from it:

    {
    "data": {
    "token": "<jwt, now carrying an install_id claim>",
    "install_id": "<id to store in your first-party cookie>"
    }
    }

This is optional - web works without it. See Guardian Web → Migrating v0.4 → v0.5 for the full flow and the ~5-line cookie relay.

Package Access Tokens​

The SDK itself is distributed as a private package. You'll also receive access tokens for package installation. These are separate from the API key above:

PlatformToken TypeWhere to Configure
React Nativenpm token.npmrc in project root
iOSGitHub token~/.netrc
AndroidGitHub tokengradle.properties

See the platform-specific installation guides for details:

Base URL​

The SDK always targets production at https://api.surt.com.

warning

Keep your sp_live_* API key server-side at all times. It is used only to mint JWTs. Never embed it in app or web client code. The client only holds JWTs, which expire after 30 minutes.