Skip to main content
Version: Guardian v0.5.3

Android

Native Android integration for the Surt Guardian SDK, distributed via Maven (GitHub Packages). The SDK collects device signals, runs device integrity checks, and returns the backend's risk decision.

The SDK never holds a Surt API key. Your backend holds the sp_live_* key (server-side only) and exchanges it for a short-lived JWT that the app passes to verify().

Version

This guide covers SDK v0.5.2.

Requirements​

  • Android SDK 24+ (Android 7.0+)
  • Kotlin 1.9+
  • Gradle 8+
  • Java 17

1. Authentication​

Add your access token to your project's gradle.properties (or ~/.gradle/gradle.properties for all projects):

gradle.properties
SURT_GITHUB_TOKEN=<YOUR_TOKEN>

Replace <YOUR_TOKEN> with the token provided by Surt.

warning

Do not commit gradle.properties with tokens to version control. Add it to .gitignore, or use ~/.gradle/gradle.properties instead.

2. Add the Repository​

In your project's settings.gradle (or settings.gradle.kts), add the Surt Maven repository:

settings.gradle
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/surtTech/surt-guardian-sdk")
credentials {
username = "surt-customer"
password = settings.ext.find("SURT_GITHUB_TOKEN")
?: System.getenv("SURT_GITHUB_TOKEN") ?: ""
}
}
}
}
settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/surtTech/surt-guardian-sdk")
credentials {
username = "surt-customer"
password = providers.gradleProperty("SURT_GITHUB_TOKEN").orNull
?: System.getenv("SURT_GITHUB_TOKEN")
}
}
}
}

3. Add the Dependency​

In your app's build.gradle (or build.gradle.kts):

build.gradle
dependencies {
implementation 'com.surt.guardian:securitysdk:0.5.2'
}
build.gradle.kts
dependencies {
implementation("com.surt.guardian:securitysdk:0.5.2")
}

Core Library Desugaring​

If your app targets minSdk < 26, ensure core library desugaring is enabled in your app's build.gradle:

build.gradle
android {
compileOptions {
coreLibraryDesugaringEnabled true
}
}

dependencies {
coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}

4. AndroidManifest Permissions​

If you enable location collection, add these permissions to your AndroidManifest.xml:

AndroidManifest.xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

If you enable SIM card info collection, add this permission:

AndroidManifest.xml
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

The SDK requests the location permission during verify() or collect() when collectLocation is enabled and you have set the current Activity (see step 6). The standard Android permission dialog appears without additional code.

The SDK does not wait for the user's answer to the permission dialog, so the call that shows the dialog carries no location. Location is included from the next call. The SDK reports the device's last known location and does not request a new position.

5. Initialize the SDK​

Call once at app startup (typically in your Application class). No API key is required in the SDK - your server-side API key never ships to the device.

MyApplication.kt
import android.app.Application
import com.surt.guardian.GuardianSDK
import com.surt.guardian.core.FailurePolicy
import com.surt.guardian.core.GuardianOptions

class MyApplication : Application() {
override fun onCreate() {
super.onCreate()

GuardianSDK.initialize(
context = this,
options = GuardianOptions(
failurePolicy = FailurePolicy.Fail,
collectLocation = true // Enable GPS collection (optional)
)
)
}
}

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

GuardianOptions also accepts logLevel, but the SDK does not apply it at initialization. It logs at INFO level.

Data Collection Options​

OptionDefaultDescription
collectLocationfalseGPS coordinates. Requires location permissions in the manifest.
collectWifiInfofalseWiFi network details. Requires ACCESS_FINE_LOCATION on Android 10 and later.
collectSimCardInfofalseSIM/carrier information. Requires the READ_PHONE_STATE permission.
collectCameraInfofalseCamera count. No permission required.

When collectLocation is enabled, the SDK prompts the user for location permission the first time verify() or collect() needs it. If the user denies, the SDK continues without GPS data.

6. Activity Reference (for automatic permission requests)​

For the SDK to show the permission dialog, it needs a reference to the current Activity. Call setActivity() in your Activity lifecycle:

MainActivity.kt
override fun onResume() {
super.onResume()
GuardianSDK.getInstance().setActivity(this)
}

override fun onPause() {
super.onPause()
GuardianSDK.getInstance().setActivity(null)
}
note

If you don't call setActivity(), the SDK still works but cannot request permissions automatically. You would need to request permissions yourself before calling verify().

7. Mint a JWT from Your Backend​

Before each verify() call, your app must fetch a JWT from your own backend. Your backend calls POST /geolocation/preflight with its server-side API key and the transaction context, then returns the JWT to the app.

Example backend call (your server, not the app):

Backend preflight request
POST /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"
}

Only transaction_type is required. See Authentication for every field.

The preflight response returns the token your app needs:

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

Your app fetches the JWT from your own backend endpoint:

Fetch JWT from your backend
suspend fun fetchVerifyJwt(): String {
// Call your OWN backend endpoint, not Surt directly
val response = httpClient.post("https://your-api.com/geolocation-jwt")
return response.body<YourJwtResponse>().jwt
}
Request a new JWT for each call

Request a new JWT immediately before calling verify(). A JWT expires 30 minutes after it is issued.

8. Verify a Transaction​

Call at security-sensitive moments (login, payment, etc.). Fetch a JWT from your backend right before each call.

Coroutines (recommended)
val jwt = fetchVerifyJwt()

// verifySuspend returns a Result. getOrThrow() throws when the call failed.
val result = GuardianSDK.getInstance().verifySuspend(jwt = jwt).getOrThrow()

if (result.allowed) {
// Proceed with the transaction
} else {
// Handle denied transaction (result.riskLevel has details)
}

Or with a callback:

Callback
val jwt = fetchVerifyJwt()

GuardianSDK.getInstance().verify(jwt = jwt) { result ->
result.onSuccess { verification ->
if (verification.allowed) { /* proceed */ }
}
result.onFailure { error ->
// error is an IOException or a SurtError. See Error Codes.
}
}

Per-call location override:

Per-call location override
// Skip location for this call, regardless of the init default
val result = GuardianSDK.getInstance().verifySuspend(
jwt = jwt,
collectLocation = false
).getOrThrow()

collectLocation = true on a call has an effect only when collectLocation was also true at initialization.

9. Collect (Server-to-Server, Optional)​

collect() returns an encrypted payload for your backend to forward to Surt. collect() does not send the device payload to Surt. Your backend sends it.

Collect payload
// Without JWT: no resolved public IP in the payload
val result = GuardianSDK.getInstance().collectSuspend().getOrThrow()

// With JWT: resolves the device public IP (GET /geolocation/client-ip)
// into the payload and applies your attestation settings
val jwtForCollect = fetchCollectJwt()
val resultWithIp = GuardianSDK.getInstance().collectSuspend(jwt = jwtForCollect).getOrThrow()

// Send result.payload to your backend
JWT is optional for collect

The JWT for collect() is optional. Pass it to resolve the device public IP into the payload and to apply your organization's attestation settings: how often a device attests, and your own Play Integrity project. Without it, the SDK attests on every call with the default project. To configure these settings, see Device attestation setup. Request a new JWT for each transaction.

Verification Result​

VerificationResult
data class VerificationResult(
val allowed: Boolean, // Backend decision - true = proceed
val riskLevel: RiskLevel, // LOW / MEDIUM / HIGH / BLOCKED / UNKNOWN
val sessionId: String, // Transaction ID for support reference
val errors: List<String>?, // Error messages, if any
val timestamp: Long, // Response timestamp (ms)
val metadata: Map<String, Any>?, // Additional backend metadata
val diagnostics: GuardianDiagnostics // What the SDK observed during the call
)

See Result diagnostics for the diagnostics fields.

Transaction Types​

These values are set by your backend in the preflight transaction_type field. They are not passed to verify() in the app.

transaction_typeUse case
loginUser login
sign_upNew account creation
depositAdding funds
withdrawalWithdrawing funds
Any other stringA custom type you define, up to 64 characters

See Transaction Types.

Troubleshooting​

ErrorCauseFix
"Could not resolve com.surt.guardian:securitysdk"Token not configured or repo not addedCheck gradle.properties and settings.gradle
"401 Unauthorized" from maven.pkg.github.comToken expired or invalidGet a new token from Surt
IllegalStateException from getInstance()getInstance() called before initialize()Call initialize() in Application.onCreate()
IOException with HTTP 401 or HTTP 403 in the messageJWT missing, malformed, or expiredRequest a new JWT from your backend for each call