Gate/AI for Android

Installation

Add the Gate/AI SDK to your Android project using Gradle. Requires Android API 24+ and Java 17+.

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.github.GateAI-net:gate-android:1.2.0")
}

// settings.gradle.kts
includeBuild("/path/to/GateAI/sdks/gate-android")

// app/build.gradle.kts
dependencies {
    implementation("com.gateai.sdk:gateai")
}

Configure the client

Initialize the Gate/AI client in your Application class with your tenant configuration.

# Debug keystore
keytool -list -v -keystore ~/.android/debug.keystore \\
  -alias androiddebugkey \\
  -storepass android -keypass android | grep SHA256

# Release keystore
keytool -list -v -keystore /path/to/release.keystore \\
  -alias your-key-alias

class MyApplication : Application() {
    lateinit var gateAIClient: GateAIClient
        private set

    override fun onCreate() {
        super.onCreate()

        val configuration = GateAIConfiguration(
            baseUrl = "https://your-team.in.gate-ai.net",
            packageName = packageName,
            signingCertSha256 = "AA:BB:CC:DD:...", // Your SHA-256 fingerprint
            cloudProjectNumber = 123456789012L, // Google Cloud project number (Play Integrity)
            logLevel = if (BuildConfig.DEBUG) 
                GateAIConfiguration.LogLevel.DEBUG 
            else 
                GateAIConfiguration.LogLevel.INFO
        )

        gateAIClient = GateAIClient.create(this, configuration)
        gateAIClient.userStatus = "premium" // Optional analytics
    }
}

Set up a development token for the Android emulator

Use a development token when testing in an Android emulator. This applies to native Android, React Native, Capacitor, and Flutter apps. The development token lets your emulator app authenticate with Gate/AI without using Google Play Integrity.

Follow the steps below, then rebuild and reinstall your debug app. The SDK discovers the token automatically, so initialize your client normally without passing the token in Kotlin, JavaScript, or Dart. Requires Android SDK 1.2.0+; included in the React Native, Capacitor, and Flutter SDKs.

1. Create a development token for your gate in the Gate/AI portal.
2. Set GATE_AI_DEV_TOKEN in the Gradle build environment, or create gateai.local.properties beside the host app’s settings.gradle or settings.gradle.kts. For framework apps this is usually the android/ directory.
3. Add gateai.local.properties to your .gitignore. In the local file, set GATE_AI_DEV_TOKEN=your-token without quotes. An environment variable takes precedence, including an explicitly empty value.
4. Add the matching snippet below to the host app module’s build file. Put Kotlin imports at the top of the file and the configuration after plugins. Merge the android / buildTypes blocks with your existing configuration. Keep the resource in the debug build type.
5. Sync Gradle, then rebuild and reinstall the debug app. Repeat this after changing the token.

Kotlin DSL · app/build.gradle.kts

// app/build.gradle.kts — put this import at the top of the file
import java.util.Properties

// Place the following after your existing plugins { ... } block.
val gateAILocalProperties = Properties().apply {
    val localFile = rootProject.file("gateai.local.properties")
    if (localFile.exists()) localFile.inputStream().use { load(it) }
}
val gateAIDevToken = providers.environmentVariable("GATE_AI_DEV_TOKEN")
    .orElse(gateAILocalProperties.getProperty("GATE_AI_DEV_TOKEN", ""))

android {
    buildTypes {
        getByName("debug") {
            resValue("string", "gate_ai_dev_token", gateAIDevToken.get())
        }
    }
}

Groovy · app/build.gradle

// app/build.gradle — place after plugins { ... }
def gateAILocalProperties = new Properties()
def gateAILocalFile = rootProject.file("gateai.local.properties")
if (gateAILocalFile.exists()) {
    gateAILocalFile.withInputStream { gateAILocalProperties.load(it) }
}
def gateAIDevToken = providers.environmentVariable("GATE_AI_DEV_TOKEN")
    .orElse(gateAILocalProperties.getProperty("GATE_AI_DEV_TOKEN", ""))

android {
    buildTypes {
        debug {
            resValue "string", "gate_ai_dev_token", gateAIDevToken.get()
        }
    }
}

Android Studio must inherit the environment variable when it starts; the ignored local file is convenient when launching the IDE from the Dock or launcher. These are build-time values, unlike iOS’s Xcode launch environment.

The SDK reads gate_ai_dev_token only in debuggable apps. If no token is configured, the SDK asks Google Play Integrity to verify the app and device instead. Explicit developmentToken configuration remains compatible and takes precedence in debug apps.

The token is present in the debug APK. Keep this resource out of defaultConfig and release build types so release APKs/AABs exclude it. The SDK also ignores all development tokens in non-debuggable apps.

Make proxied requests

Use `performProxyRequest()` for complete request handling with automatic DPoP nonce retry.

class MyViewModel(application: Application) : AndroidViewModel(application) {
    private val gateAI = (application as MyApplication).gateAIClient

    fun callOpenAI() {
        viewModelScope.launch {
            try {
                val requestBody = """
                {
                    "model": "gpt-4o",
                    "messages": [
                        {"role": "user", "content": "Say hello from Gate/AI"}
                    ]
                }
                """.trimIndent()

                val response = gateAI.performProxyRequest(
                    path = "openai/chat/completions",
                    method = HttpMethod.POST,
                    body = requestBody.toByteArray(),
                    additionalHeaders = mapOf("Content-Type" to "application/json")
                )

                if (response.status == 200) {
                    val result = response.body
                    // Process response
                }
            } catch (e: GateApiException) {
                // Handle HTTP errors (400, 401, etc.)
                Log.e("GateAI", "Error: ${e.statusCode} - ${e.body}")
            } catch (e: Exception) {
                // Handle other errors
                Log.e("GateAI", "Error", e)
            }
        }
    }
}

Manual request integration

Use a custom networking stack? Pull headers from the client and handle nonce challenges manually.

// Get authorization headers
val headers = gateAI.authorizationHeaders(
    path = "anthropic/v1/messages",
    method = HttpMethod.POST
)

// Use with your HTTP client
val request = Request.Builder()
    .url("https://your-team.in.gate-ai.net/anthropic/v1/messages")
    .post(requestBody)
    .apply {
        headers.forEach { (key, value) ->
            addHeader(key, value)
        }
        addHeader("Content-Type", "application/json")
    }
    .build()

val response = httpClient.newCall(request).execute()

// Handle DPoP nonce challenge (401)
if (response.code == 401) {
    val nonce = gateAI.extractDPoPNonce(response.headers.toMultimap())
    if (nonce != null) {
        // Retry with nonce
        val retryHeaders = gateAI.authorizationHeaders(
            path = "anthropic/v1/messages",
            method = HttpMethod.POST,
            nonce = nonce
        )
        // Make request again with retryHeaders
    }
}

SDK features

• 🔐 Hardware-backed keys

  P-256 ECDSA keys in Android Keystore with StrongBox preference on supported devices (Android 9+).

• 📱 Play Integrity attestation

  Automatic device verification using Google Play Integrity API with MEETS_DEVICE_INTEGRITY minimum.

• ♻️ Automatic token refresh

  Tokens cached in-memory and refreshed 60 seconds before expiry with mutex-based thread safety.

• 🔄 DPoP nonce retry

  Automatic handling of 401 DPoP-Nonce challenges with transparent request retry.

• 📊 Analytics headers

  Automatic inclusion of device info, app version, OS version, locale, environment, and SDK version on all requests, plus optional user and feature attribution.

• 🧪 Development token flow

  Test on emulators using development tokens when Play Integrity is unavailable.

Analytics headers

The SDK automatically includes analytics headers on all requests for usage tracking and insights.

// X-User-Status: user segment or subscription tier
client.userStatus = "premium"

// X-User-Identifier: opaque account ID from your
// own system — never an email or name
client.userIdentifier = account.analyticsId

// X-App-Feature: which in-app feature is making
// AI requests, for per-feature cost attribution
client.appFeature = "chat"

// X-User-Tier: the user's plan tier — per-tier usage
// limits configured for this gate match it exactly
client.userTier = "pro"

Usage limits & quotas

Gates can enforce per-device budgets over daily, calendar-month, rolling 30-day, and billing-cycle windows. The SDK reports the user's renewal day and surfaces remaining quota so you can render limit UI, and per-tier limits key off the client's userTier value — and make hitting a cap your upgrade moment.

// Day-of-month (1–31) the user's subscription renews
client.quotaAnchorDay = renewalDayOfMonth

{ "error": "rate_limited",
  "code": "device_monthly_requests_exceeded",
  "window": "monthly", "limit": 200, "used": 200,
  "resets_at": "2026-10-01T00:00:00.000Z" }

API reference

fun create(
    context: Context,
    configuration: GateAIConfiguration,
    logger: GateLogger = AndroidGateLogger()
): GateAIClient

suspend fun performProxyRequest(
    path: String,
    method: HttpMethod,
    body: ByteArray? = null,
    additionalHeaders: Map = emptyMap()
): RawResponse

suspend fun authorizationHeaders(
    path: String,
    method: HttpMethod,
    nonce: String? = null
): Map

suspend fun currentAccessToken(): String?

fun clearCachedState()

Error handling

The SDK throws structured exceptions for different error scenarios.

try {
    val response = gateAI.performProxyRequest(...)
} catch (e: GateApiException) {
    // HTTP errors (400, 401, 403, 429, 500, etc.)
    when (e.statusCode) {
        401 -> Log.e("Auth", "Unauthorized: ${e.body}")
        403 -> Log.e("Auth", "Forbidden: ${e.body}")
        429 -> Log.e("RateLimit", "Rate limited: ${e.body}")
        else -> Log.e("API", "Error ${e.statusCode}: ${e.body}")
    }
} catch (e: Exception) {
    // Network errors, timeouts, etc.
    Log.e("Network", "Request failed", e)
}

Requirements

• Min SDK: Android 7.0 (API 24)
• Target SDK: Android 14 (API 34)
• Kotlin: 2.1.0+
• Java: 17
• Play Integrity: Required for production (development token for emulators)

Troubleshooting