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() - the attestation nonce bound to the JWT's attestation_challenge is single-use (App Attest / Play Integrity). Reusing a JWT causes attestation to fail.
• collect() JWT is optional - pass it only to embed the device's public IP in the payload. Because collect() generates its own nonce, its 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.

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

Environments

Environment	Base URL	Use
production	https://api.surt.com	Live traffic
sandbox	https://sandbox-api.surt.com	Testing and development

warnung

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.