android-kotlin

---
name: android-kotlin
description: Add authdog sign-in to a native Android/Kotlin app using Custom Tabs, EncryptedSharedPreferences-backed sessions, and the authdog REST API. Use when the user asks to integrate authdog auth into an Android Kotlin app (Activity or Compose).
---

# authdog for Android (Kotlin)

> **No official Kotlin SDK yet.** authdog ships SDKs for Node.js, Python, Go, Rust, Java, and C#, plus a React Native/Expo package (`@authdog/react-native`). Kotlin is tracked as a planned SDK in [authdog/sdk](https://github.com/authdog/sdk) but isn't published. This skill is the native-Android integration **pattern** — talk to the authdog REST API directly with Custom Tabs and `EncryptedSharedPreferences`, mirroring the same deep-link + secure-storage flow the Expo SDK uses under the hood. Swap in the real SDK once it ships; the steps below (redirect config, token storage, `/v1/userinfo`) will still apply.

## When to use this skill

The user wants to add "Sign in with authdog" (or authdog session handling) to a native Android/Kotlin app — View-based Activities or Jetpack Compose, Gradle module.

## What you need from the user first

1. Their authdog **public key** (`pk_...`), from the [authdog console](https://console.authdog.com/) → Project settings. Never ask for or use the secret key (`sk_...`) client-side — that's backend-only.
2. Their app's application ID / package name, to build a callback URL scheme (a `deep link` / app link).

## Overview

authdog's browser-based sign-in flow, adapted to Android:

1. App launches a Custom Tab pointed at the authdog-hosted sign-in page, with a custom URL scheme (or App Link) as the redirect target (same pattern as the Expo SDK's deep-link callback).
2. User authenticates in the system browser tab.
3. authdog redirects back to `<scheme>://callback?...` with a session token.
4. The app captures that token via an intent filter, stores it in `EncryptedSharedPreferences`, and uses it as a Bearer token against authdog's REST API (starting with `GET /v1/userinfo`).

## Steps

### 1. Register a callback URL scheme

In the authdog console, under **Redirects** for your project, add a callback URL using your app's custom scheme, e.g.:

```
myapp://callback
```

This is the same setting the Expo guide calls the deep-link callback — for a native app it's a custom URL scheme (or an App Link / `https` URI) instead of a universal link.

### 2. Add the intent filter to your app

In `AndroidManifest.xml`, register an intent filter for the callback scheme on the Activity that should receive the redirect:

```xml
<activity android:name=".AuthCallbackActivity">
    <intent-filter android:autoVerify="false">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" android:host="callback" />
    </intent-filter>
</activity>
```

For App Links (verified `https` redirects) use `android:autoVerify="true"` and a `https` host you control, plus a hosted `assetlinks.json`. The custom-scheme path above is the simpler default.

### 3. Store your public key

Don't hardcode it. Add it to your build config (e.g. via `build.gradle.kts` `buildConfigField`) or `local.properties`, and read it at runtime:

```kotlin
object AuthdogConfig {
    const val publicKey = BuildConfig.AUTHDOG_PUBLIC_KEY
    const val redirectUri = "myapp://callback"
    const val signInUrl = "https://auth.authdog.com/sign-in" // confirm exact host in your console
}
```

```kotlin
// build.gradle.kts (module)
android {
    buildFeatures {
        buildConfig = true
    }
    defaultConfig {
        val pk = project.findProperty("authdogPublicKey") as String? ?: ""
        buildConfigField("String", "AUTHDOG_PUBLIC_KEY", "\"$pk\"")
    }
}
```

### 4. Add the dependencies

```kotlin
// build.gradle.kts (module)
dependencies {
    implementation("androidx.browser:browser:1.8.0")          // CustomTabsClient
    implementation("androidx.security:security-crypto:1.1.0-alpha06") // EncryptedSharedPreferences
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0")
    // networking — pick one. kotlinx.serialization shown:
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3")
}
```

### 5. Build the auth service

```kotlin
package com.example.authdog

import android.content.Context
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent
import androidx.security.crypto.EncryptedSharedPreferences
import androidx.security.crypto.MasterKey
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow

class AuthdogService(private val context: Context) {

    private val _isAuthenticated = MutableStateFlow(false)
    val isAuthenticated: StateFlow<Boolean> = _isAuthenticated.asStateFlow()

    private val _accessToken = MutableStateFlow<String?>(null)
    val accessToken: StateFlow<String?> = _accessToken.asStateFlow()

    private val prefs by lazy {
        val masterKey = MasterKey.Builder(context)
            .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
            .build()
        EncryptedSharedPreferences.create(
            context,
            "authdog",
            masterKey,
            EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
            EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
        )
    }

    fun signIn() {
        val signInUri = Uri.parse(AuthdogConfig.signInUrl)
            .buildUpon()
            .appendQueryParameter("public_key", AuthdogConfig.publicKey)
            .appendQueryParameter("redirect_uri", AuthdogConfig.redirectUri)
            .build()

        val intent = CustomTabsIntent.Builder()
            .setShowTitle(false)
            .build()
        // launch in a fresh task so the browser tab doesn't pile on our back stack
        intent.intent.addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK)
        intent.launchUrl(context, signInUri)
    }

    /** Call from your callback Activity's onCreate / onNewIntent. */
    fun handleRedirect(uri: Uri): Boolean {
        val token = uri.getQueryParameter("token") ?: return false
        prefs.edit().putString(KEY_ACCESS_TOKEN, token).apply()
        _accessToken.value = token
        _isAuthenticated.value = true
        return true
    }

    fun restoreSession() {
        val token = prefs.getString(KEY_ACCESS_TOKEN, null)
        if (token != null) {
            _accessToken.value = token
            _isAuthenticated.value = true
        }
    }

    fun signOut() {
        prefs.edit().remove(KEY_ACCESS_TOKEN).apply()
        _accessToken.value = null
        _isAuthenticated.value = false
    }

    companion object {
        private const val KEY_ACCESS_TOKEN = "authdog.accessToken"
    }
}
```

> Confirm the exact sign-in host and the redirect query param name (`token` above is illustrative) against your project's console settings before shipping — the hosted sign-in page's response shape isn't guaranteed by this skill.

### 6. Capture the redirect

```kotlin
class AuthCallbackActivity : AppCompatActivity() {

    private val authdog by lazy { AuthdogService(applicationContext) }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        handle(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handle(intent)
    }

    private fun handle(intent: Intent?) {
        val data = intent?.data ?: return finish()
        if (authdog.handleRedirect(data)) {
            // route to your post-sign-in destination
            startActivity(Intent(this, MainActivity::class.java))
        }
        finish()
    }
}
```

### 7. Fetch the signed-in user

authdog's SDKs all wrap one endpoint for this — call it directly with OkHttp:

```kotlin
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import okhttp3.OkHttpClient
import okhttp3.Request

@Serializable
data class AuthdogUser(
    val sub: String,
    val email: String? = null,
    val picture: String? = null,
    val emailVerified: Boolean? = null
)

class AuthdogApi(private val client: OkHttpClient = OkHttpClient()) {

    suspend fun fetchUser(accessToken: String): AuthdogUser =
        withContext(Dispatchers.IO) {
            val request = Request.Builder()
                .url("https://api.authdog.com/v1/userinfo")
                .header("Authorization", "Bearer $accessToken")
                .build()

            client.newCall(request).execute().use { resp ->
                if (!resp.isSuccessful) throw IOException("userinfo failed: ${resp.code}")
                Json { ignoreUnknownKeys = true }
                    .decodeFromString(resp.body!!.string())
            }
        }
}
```

Confirm the exact API host (`api.authdog.com` above is illustrative) and response fields against your project's docs — field names should match `useUser()`'s shape in the React Native SDK, but verify before relying on them.

### 8. Wire it into Jetpack Compose

```kotlin
@Composable
fun RootView(authdog: AuthdogService) {
    val isAuthenticated by authdog.isAuthenticated.collectAsState()
    LaunchedEffect(Unit) { authdog.restoreSession() }

    if (isAuthenticated) {
        HomeScreen(authdog = authdog)
    } else {
        Button(onClick = { authdog.signIn() }) { Text("Sign in") }
    }
}
```

### 9. Validate tokens server-side for anything sensitive

Same rule as the Expo guide: treat the client-held token as a bearer credential for calling authdog's API, not as proof of identity for your own backend. If you have a backend, validate the token there (e.g. via `@authdog/fastify`, `@authdog/nextjs-app`, or the equivalent server SDK for your stack) before trusting it for privileged actions.

## Gotchas

- **Custom Tabs vs WebView**: always use Custom Tabs (or ChromeOS's system browser). A WebView can't share cookies with the system browser, so SSO across apps and the browser breaks.
- **Scheme collisions**: pick a scheme unlikely to collide with other apps (e.g. `com.yourcompany.yourapp` style rather than `myapp`). For verified links, prefer App Links.
- **`launchUrl` from a non-Activity context**: the `FLAG_ACTIVITY_NEW_TASK` snippet above handles that; if you call from an Activity, you can drop the flag.
- **Backup exclusion**: exclude `authdog` prefs from auto-backup so a restored device image doesn't resurrect a stale session. Add `fullBackupContent` rules or `android:allowBackup="false"` on the relevant element.
- **This is a bridge, not the SDK**: once `authdog/sdk` publishes Kotlin, migrate to it — this skill's `EncryptedSharedPreferences`/Custom Tabs code is exactly what a real SDK would absorb.

## Next steps

- [Backend requests](https://www.authdog.com/docs/backend): validate the same session on your API.
- [Calling the REST API](https://www.authdog.com/docs/api)
- [Authorization](https://www.authdog.com/docs/concepts/authorization)

More agent context in authdog/agent-skills

31 other files this repository gives its agents.