Authentication

API Key

Guardian uses an sp_live_* API key provided by the Surt team - but in v0.3.0 that key is held by your backend only. It is used to mint short-lived JWTs and never ships to the client (mobile app or web). The client only ever holds the short-lived 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 (v0.3.0)

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:

• Fresh JWT per verify() - each JWT is single-use. Reusing one is rejected by the backend.
• collect() JWT is optional - pass it only to embed the device's public IP in the payload. A collect() JWT may be reused or omitted entirely.

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

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.

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 SDK reads automatically. 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:

Platform	Token Type	Where to Configure
React Native	npm token	.npmrc in project root
iOS	GitHub token	~/.netrc
Android	GitHub token	gradle.properties

See the platform-specific installation guides for details:

• React Native
• iOS
• Android

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 short-lived JWTs. Never embed it in app or web client code. The client only ever holds short-lived JWTs.