Skip to main content

Overview

📱 GuardianKey Mobile SDK​

The GuardianKey Mobile SDK brings Auth Security XE (checkaccessxe) to native mobile apps. It is a Kotlin Multiplatform (KMP) library that you call at the login step of your own Android/iOS application — exactly the way the reference demo app does. For each login attempt the SDK collects device and behavioral information, builds a gkas_solution token, and your backend forwards it to GuardianKey, which returns a risk decision (ALLOW / BLOCK).

It is the mobile equivalent of the web collector: where the browser runs a JavaScript snippet on the login form, the SDK runs the same logic natively.

🔒 The contents and format of gkas_solution are intentionally not documented — treat it as an opaque token. You never need to read, build or parse it: the SDK produces it, your app forwards it to your backend, and your backend forwards it unchanged to checkaccessxe. This page and the integration guides cover everything required to integrate; the internal payload is a black box by design.

🧩 What you integrate​

PieceWho provides itRole
Mobile SDK (io.guardiankey.gkas)GuardianKey (this SDK)Collects signals, builds the gkas_solution token, talks to your backend.
Your app (Android/iOS)YouCalls the SDK during login and reacts to the decision.
Your backend (REST)YouExposes GET /config and POST /login; calls checkaccessxe server‑side with your GuardianKey credentials.

🔐 GuardianKey credentials (key/iv/agentId/…) live only on your backend. The mobile app never holds them. The app only talks to your backend.

🔄 Login flow​

The SDK exposes three calls. A login screen drives them in order:

        ┌─────────────┐   1. fetchConfig()      ┌──────────────┐
        │   Your app  │ ──────────────────────▶ │ Your backend │  GET /config
        │  (login UI) │ ◀────────────────────── │   (REST)     │  → salt, once, time, policy, url
        └─────────────┘   salt/once/time/policy └──────────────┘
              │
              │ 2. buildSolution(config, username)
              │    collect signals + resolve identity → gkas_solution (opaque token)
              ▼
        ┌─────────────┐   3. login(LoginRequest) ┌──────────────┐   checkaccessxe   ┌────────────┐
        │   Your app  │ ──────────────────────▶  │ Your backend │ ────────────────▶ │ GuardianKey│
        │             │ ◀──────────────────────  │              │ ◀──────────────── │    XE      │
        └─────────────┘   decision: ALLOW|BLOCK  └──────────────┘   risk decision   └────────────┘
              │
              ├─ ALLOW → enter the app (Home)
              └─ BLOCK → stay on login, show the block message
  1. fetchConfig() — GET /config returns salt, once (one‑time nonce), time, url and a policy that tells the SDK which identity tier to use.
  2. buildSolution(config, username) — collects signals, resolves the device identity, and returns the gkas_solution (an opaque token). username is the field value bound to this attempt.
  3. login(LoginRequest(...)) — POST /login with the credentials and the gkas_solution. The backend validates/consumes the once, calls checkaccessxe, and returns a normalized decision.

🪪 Device identity tiers​

The backend's policy.tiers selects, in cascade with fallback, how the device identifies itself for the attempt. The only thing the integrator needs to know is the user‑facing behavior:

TierUser experience
biometricShows a biometric prompt (fingerprint/face) during login.
softwareSilent — no prompt.
uuidSilent fallback when stronger tiers are unavailable.

On iOS the same tiers map to the platform's native mechanisms (currently provided as compilable stubs — see the iOS page).

📦 Collected signals​

During buildSolution() the SDK gathers a range of device and behavioral information (such as biometric/identity signals, touch behavior, among others) and packs it into the opaque gkas_solution token.

What matters for integration:

  • Best‑effort, never blocks login. Every collector tolerates missing permissions or unavailable hardware — if something can't be read, it is simply omitted and login still proceeds.
  • No typed content is captured (e.g. behavioral touch signals record timing, not what the user types).
  • Permissions are optional. Granting more runtime permissions yields richer signals, but denying them never breaks the flow. See the Android guide for the permission list.

⏭️ Next steps​