Referencia de SDK de autenticación

Instalación

Add InsForge dependencies to your project

Maven Central
GitHub Packages

build.gradle.kts:

repositories {
    mavenLocal() // For local development
    mavenCentral()
}

dependencies {
    implementation("dev.insforge:insforge-kotlin:0.1.6")
}

First, create a GitHub Personal Access Token:

Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Select permission: read:packages

Then configure your project using one of the following methods:

Option A: Environment Variables

settings.gradle.kts (or build.gradle.kts):

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/InsForge/insforge-kotlin")
        credentials {
            username = System.getenv("GITHUB_USER") ?: ""
            password = System.getenv("GITHUB_TOKEN") ?: ""
        }
    }
}

build.gradle.kts:

dependencies {
    implementation("dev.insforge:insforge-kotlin:0.1.6")
}

Set environment variables before building:

export GITHUB_USER="your-github-username"
export GITHUB_TOKEN="your-personal-access-token"

Option B: gradle.properties (Local Development)

Add credentials to your global Gradle properties file:~/.gradle/gradle.properties:

gpr.user=your-github-username
gpr.token=ghp_xxxxxxxxxxxx

settings.gradle.kts:

repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/InsForge/insforge-kotlin")
        credentials {
            username = providers.gradleProperty("gpr.user").orNull ?: ""
            password = providers.gradleProperty("gpr.token").orNull ?: ""
        }
    }
}

build.gradle.kts:

dependencies {
    implementation("dev.insforge:insforge-kotlin:0.1.6")
}

The ~/.gradle/gradle.properties file is stored outside your project, so credentials won’t be accidentally committed to version control.

Initialize InsForge SDK

import dev.insforge.createInsforgeClient
import dev.insforge.auth.Auth
import dev.insforge.database.Database
import dev.insforge.storage.Storage
import dev.insforge.functions.Functions
import dev.insforge.realtime.Realtime
import dev.insforge.ai.AI

val client = createInsforgeClient(
    baseUrl = "https://your-app.insforge.app",
    anonKey = "your-api-key"
) {
    install(Auth)
    install(Database)
    install(Storage)
    install(Functions)
    install(Realtime) {
        autoReconnect = true
        reconnectDelay = 5000
    }
    install(AI)
}

Enable Logging (Optional)

For debugging, you can configure the SDK log level:

import dev.insforge.InsforgeLogLevel

val client = createInsforgeClient(
    baseUrl = "https://your-app.insforge.app",
    anonKey = "your-api-key"
) {
    // DEBUG: logs request method/URL and response status
    // VERBOSE: logs full headers and request/response bodies
    logLevel = InsforgeLogLevel.DEBUG

    install(Auth)
    install(Database)
    // ... other modules
}

Log Level	Description
`NONE`	No logging (default, recommended for production)
`ERROR`	Only errors
`WARN`	Warnings and errors
`INFO`	Informational messages
`DEBUG`	Debug info (request method, URL, response status)
`VERBOSE`	Full details (headers, request/response bodies)

Use NONE or ERROR in production to avoid exposing sensitive data in logs.

Android Initialization

Add Chrome Custom Tabs dependency to your build.gradle.kts:

dependencies {
    implementation("androidx.browser:browser:1.9.0")
}

Initialize InsForge SDK (With Chrome Custom Tabs and Session Storage)

import android.app.Activity
import android.content.Context
import android.content.Intent
import android.net.Uri
import androidx.browser.customtabs.CustomTabsIntent
import dev.insforge.createInsforgeClient
import dev.insforge.ai.AI
import dev.insforge.auth.Auth
import dev.insforge.auth.BrowserLauncher
import dev.insforge.auth.ClientType
import dev.insforge.auth.SessionStorage
import dev.insforge.database.Database
import dev.insforge.functions.Functions
import dev.insforge.realtime.Realtime
import dev.insforge.storage.Storage

class InsforgeManager(private val context: Context) {

    val client = createInsforgeClient(
        baseUrl = "https://your-app.insforge.app",
        anonKey = "your-anon-key"
    ) {
        install(Auth) {
            // 1. Chrome Custom Tabs - opens in-app, similar to iOS ASWebAuthenticationSession
            browserLauncher = BrowserLauncher { url ->
                val customTabsIntent = CustomTabsIntent.Builder()
                    .setShowTitle(true)
                    .build()
                // Handle non-Activity context safely
                if (context is Activity) {
                    customTabsIntent.launchUrl(context, Uri.parse(url))
                } else {
                    customTabsIntent.intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
                    customTabsIntent.launchUrl(context, Uri.parse(url))
                }
            }

            // 2. enable session persistence
            persistSession = true

            // 3. config SessionStorage (use SharedPreferences)
            sessionStorage = object : SessionStorage {
                private val prefs = context.getSharedPreferences(
                    "insforge_auth",
                    Context.MODE_PRIVATE
                )

                override suspend fun save(key: String, value: String) {
                    prefs.edit().putString(key, value).apply()
                }

                override suspend fun get(key: String): String? {
                    return prefs.getString(key, null)
                }

                override suspend fun remove(key: String) {
                    prefs.edit().remove(key).apply()
                }
            }

            // 4. set client type for mobile
            clientType = ClientType.MOBILE
        }
        // Install Database module
        install(Database)

        // Install Realtime module for real-time subscriptions
        install(Realtime) {
            debug = true
        }
        // Install other modules
        install(Storage)
        install(Functions)
        install(AI)
    }
}

Use Jetpack DataStore for Session Storage (Optional)

import androidx.datastore.core.DataStore
import androidx.datastore.preferences.core.Preferences
import androidx.datastore.preferences.core.edit
import androidx.datastore.preferences.core.stringPreferencesKey
import androidx.datastore.preferences.preferencesDataStore
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.map

val Context.authDataStore: DataStore<Preferences> by preferencesDataStore(name = "insforge_auth")

class DataStoreSessionStorage(private val context: Context) : SessionStorage {
    
    override suspend fun save(key: String, value: String) {
        context.authDataStore.edit { prefs ->
            prefs[stringPreferencesKey(key)] = value
        }
    }
    
    override suspend fun get(key: String): String? {
        return context.authDataStore.data.map { prefs ->
            prefs[stringPreferencesKey(key)]
        }.first()
    }
    
    override suspend fun remove(key: String) {
        context.authDataStore.edit { prefs ->
            prefs.remove(stringPreferencesKey(key))
        }
    }
}

// Then use it in your InsForge client
install(Auth) {
    browserLauncher = ...
    persistSession = true
    sessionStorage = DataStoreSessionStorage(context)
}

Crear una nueva cuenta de usuario con correo electrónico y contraseña.

Parámetros

email (String) - Dirección de correo electrónico del usuario
password (String) - Contraseña del usuario
name (String?, optional) - Nombre de visualización del usuario

Devuelve

SignUpResponse

SignUpResponse

data class SignUpResponse(
    /** User object (null when email verification is required) */
    val user: User? = null,
    /** Access token (null when email verification is required) */
    val accessToken: String? = null,
    /** Indicates if email verification is required before sign-in */
    val requireEmailVerification: Boolean = false,
    /** Redirect URL (if applicable) */
    val redirectTo: String? = null,
    /** CSRF token (if applicable) */
    val csrfToken: String? = null,
    /** Refresh token (null when email verification is required) */
    val refreshToken: String? = null
)

Ejemplo (Flujo completo con verificación)

class AuthViewModel : ViewModel() {

    // Sign up and handle verification requirement
    suspend fun signUp(email: String, password: String, name: String?) {
        try {
            val result = client.auth.signUp(
                email = email,
                password = password,
                name = name
            )

            if (result.requireEmailVerification) {
                // Show verification code input screen
                // User will receive a 6-digit code via email
                _uiState.value = AuthUiState.RequiresVerification(email)
            } else if (result.accessToken != null) {
                // Registration complete, user is signed in
                _uiState.value = AuthUiState.Authenticated
            }
        } catch (e: InsforgeHttpException) {
            _uiState.value = AuthUiState.Error(e.message ?: "Sign up failed")
        }
    }

    // Verify email with 6-digit code
    suspend fun verifyEmail(email: String, code: String) {
        try {
            client.auth.verifyEmail(email = email, code = code)
            // Verification successful, user can now sign in
            _uiState.value = AuthUiState.VerificationSuccess
        } catch (e: InsforgeHttpException) {
            _uiState.value = AuthUiState.Error("Invalid verification code")
        }
    }

    // Resend verification email
    suspend fun resendVerificationEmail(email: String) {
        try {
            client.auth.resendVerificationEmail(email = email)
            // Show success message
        } catch (e: InsforgeHttpException) {
            _uiState.value = AuthUiState.Error("Failed to resend verification email")
        }
    }
}

sealed class AuthUiState {
    object Initial : AuthUiState()
    object Authenticated : AuthUiState()
    object VerificationSuccess : AuthUiState()
    data class RequiresVerification(val email: String) : AuthUiState()
    data class Error(val message: String) : AuthUiState()
}

Verificación de correo electrónico

Para los usuarios que se registran con correo electrónico, el backend de InsForge proporciona tres opciones:

Sin verificación de correo electrónico - Los usuarios pueden iniciar sesión inmediatamente después del registro. SignUpResponse tendrá accessToken != null.
Verificación basada en enlaces - Los usuarios deben abrir su correo electrónico y hacer clic en el enlace de verificación antes de poder iniciar sesión.
Verificación basada en código - El backend de InsForge envía un código de verificación de 6 dígitos al correo electrónico del usuario. La aplicación cliente necesita mostrar una pantalla de verificación donde los usuarios puedan ingresar el código, luego llamar a verifyEmail(email, code) para completar la verificación. Solo después de esto, los usuarios pueden iniciar sesión con correo electrónico + contraseña.

Cuando requireEmailVerification es true, la respuesta tendrá:

accessToken = null
user = null
requireEmailVerification = true

Esto indica que la verificación mediante la opción 2 o 3 es necesaria antes de que el usuario pueda iniciar sesión.

Métodos relacionados

Método	Descripción
`verifyEmail(email, code)`	Verificar correo electrónico con código de 6 dígitos
`resendVerificationEmail(email)`	Reenviar correo electrónico de verificación

Iniciar sesión con un usuario existente usando correo electrónico y contraseña.

Ejemplo

try {
    val result = client.auth.signIn(
        email = "user@example.com",
        password = "secure_password123"
    )

    result.user?.let { user ->
        Log.d("Auth", "Welcome back, ${user.profile?.name ?: user.email}")
    }
} catch (e: InsforgeHttpException) {
    Log.e("Auth", "Sign in failed: ${e.message}")
}

Verificación de correo electrónico

Si la respuesta de inicio de sesión es:

{"error":"FORBIDDEN","message":"Email verification required","statusCode":403,"nextActions":"Please verify your email address before logging in"}

Esto indica que la verificación mediante la opción 2 o 3 (enlace o código, consulta signUp()) es necesaria antes de que el usuario pueda iniciar sesión.

signOut()

Cerrar la sesión del usuario actual.

Ejemplo

try {
    client.auth.signOut()
    Log.d("Auth", "User signed out")
} catch (e: InsforgeException) {
    Log.e("Auth", "Sign out failed: ${e.message}")
}

signInWithOAuthPage()

Inicia sesión directamente con un proveedor OAuth específico. Este método abre la página de autenticación del proveedor OAuth directamente en el navegador del sistema.

Proveedores admitidos

enum class OAuthProvider(val value: String) {
    GOOGLE("google"),
    GITHUB("github"),
    DISCORD("discord"),
    LINKEDIN("linkedin"),
    FACEBOOK("facebook"),
    INSTAGRAM("instagram"),
    TIKTOK("tiktok"),
    APPLE("apple"),
    X("x"),
    SPOTIFY("spotify"),
    MICROSOFT("microsoft")
}

Parámetros

provider (OAuthProvider) - El proveedor OAuth con el que autenticarse
redirectUri (String) - URL de devolución de llamada donde InsForge redirigirá después de la autenticación

Devuelve

String  // The OAuth authorization URL (also opens in browser automatically)

Ejemplo

Configurar BrowserLauncher

Al crear el cliente de InsForge, configura el browserLauncher para manejar la apertura de URLs:

val client = createInsforgeClient(baseURL, anonKey) {
    install(Auth) {
        browserLauncher = BrowserLauncher { url ->
            val customTabsIntent = CustomTabsIntent.Builder()
                .setShowTitle(true)
                .build()
            // Handle non-Activity context safely
            if (context is Activity) {
                customTabsIntent.launchUrl(context, Uri.parse(url))
            } else {
                customTabsIntent.intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
                customTabsIntent.launchUrl(context, Uri.parse(url))
            }
        }
        persistSession = true
        sessionStorage = mySessionStorage
    }
}

Configurar devolución de llamada de App Link / Deep Link

Configura tu actividad de devolución de llamada en AndroidManifest.xml:

Opción A: Esquema de URL personalizado (para desarrollo)

<activity
    android:name=".AuthCallbackActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="yourapp" android:host="auth" android:path="/callback" />
    </intent-filter>
</activity>

Opción B: App Links (para producción)

<activity
    android:name=".AuthCallbackActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="yourdomain.com" android:path="/auth/callback" />
    </intent-filter>
</activity>

Iniciar inicio de sesión con OAuth con proveedor específico

// Start OAuth flow with Google
fun startGoogleLogin() {
    lifecycleScope.launch {
        val authUrl = client.auth.signInWithOAuthPage(
            OAuthProvider.GOOGLE,
            "yourapp://auth/callback"
        )
        // Browser opens automatically via browserLauncher
    }
}

Manejar devolución de llamada de OAuth

class AuthCallbackActivity : AppCompatActivity() {
    // Example: read the shared InsForge client from your Application class.
    private val client by lazy { (application as MyApp).insforgeClient }

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

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        intent?.let { handleIntent(it) }
    }

    private fun handleIntent(intent: Intent) {
        intent.data?.let { uri ->
            lifecycleScope.launch {
                try {
                    val result = client.auth.handleAuthCallback(uri.toString())

                    Toast.makeText(
                        this@AuthCallbackActivity,
                        "Success: ${result.email}",
                        Toast.LENGTH_SHORT
                    ).show()

                    startActivity(Intent(this@AuthCallbackActivity, MainActivity::class.java))
                    finish()
                } catch (e: Exception) {
                    Toast.makeText(
                        this@AuthCallbackActivity,
                        "Failed: ${e.message}",
                        Toast.LENGTH_LONG
                    ).show()
                    finish()
                }
            }
        }
    }
}

client debe provenir de la misma instancia compartida del cliente de InsForge que utilizas en otros lugares de la aplicación, como un singleton de Application o tu contenedor de inyección de dependencias.

getCurrentUser()

Obtener el usuario autenticado actual del servidor. Esta es una función suspensiva que realiza una solicitud de red.

Devuelve

CurrentUserResponse  // Contains user data from server

Ejemplo

try {
    val response = client.auth.getCurrentUser()
    Log.d("Auth", "Email: ${response.email}")
    Log.d("Auth", "Name: ${response.profile?.name ?: "N/A"}")
} catch (e: InsforgeHttpException) {
    Log.e("Auth", "Failed to get user: ${e.message}")
}

Este método realiza una solicitud de red para obtener datos del usuario. Para acceder al estado del usuario almacenado en caché localmente, utiliza currentUser StateFlow.

updateProfile()

Actualizar el perfil del usuario actual.

Parámetros

profile (Map\<String, Any\>) - Campos de perfil a actualizar

Devuelve

ProfileResponse  // Updated profile data

Ejemplo

try {
    val result = client.auth.updateProfile(
        mapOf(
            "name" to "JohnDev",
            "bio" to "Android Developer",
            "avatar_url" to "https://example.com/avatar.jpg"
        )
    )
    Log.d("Auth", "Profile updated: ${result.name}")
} catch (e: InsforgeHttpException) {
    Log.e("Auth", "Update failed: ${e.message}")
}

Restablecimiento de contraseña

InsForge admite dos métodos de restablecimiento de contraseña, configurados en el backend:

Método de código: El usuario recibe un código de 6 dígitos por correo electrónico, lo verifica para obtener un token de restablecimiento y luego restablece la contraseña
Método de enlace: El usuario recibe un enlace mágico por correo electrónico que contiene el token de restablecimiento y luego restablece la contraseña directamente

sendPasswordReset()

Envía un correo electrónico de restablecimiento de contraseña al usuario. El correo electrónico contendrá un código de 6 dígitos o un enlace mágico según la configuración del backend.

Parámetros

email (String) - Dirección de correo electrónico del usuario

Ejemplo

try {
    client.auth.sendPasswordReset(email = "user@example.com")
    // Show message to check email
    showMessage("If your email is registered, you will receive a password reset email.")
} catch (e: InsforgeHttpException) {
    Log.e("Auth", "Failed to send reset email: ${e.message}")
}

exchangeResetPasswordToken()

Intercambia un código de restablecimiento de 6 dígitos por un token de restablecimiento. Este método solo se usa con el flujo de restablecimiento basado en código.

Parámetros

email (String) - Dirección de correo electrónico del usuario
code (String) - Código numérico de 6 dígitos recibido por correo electrónico

Devuelve

ResetTokenResponse

ResetTokenResponse

data class ResetTokenResponse(
    /** Reset token to use with resetPassword() */
    val token: String,
    /** Token expiration timestamp */
    val expiresAt: String?
)

Ejemplo

try {
    val response = client.auth.exchangeResetPasswordToken(
        email = "user@example.com",
        code = "123456"
    )
    // Store the token and proceed to password reset screen
    val resetToken = response.token
    showPasswordResetScreen(token = resetToken)
} catch (e: InsforgeHttpException) {
    Log.e("Auth", "Invalid or expired code: ${e.message}")
}

resetPassword()

Restablecer la contraseña del usuario usando un token de restablecimiento.

Parámetros

newPassword (String) - Nueva contraseña que cumple con los requisitos configurados
otp (String) - Token de restablecimiento (de exchangeResetPasswordToken() para flujo de código, o de URL de enlace mágico para flujo de enlace)

Ejemplo

try {
    client.auth.resetPassword(
        newPassword = "newSecurePassword123",
        otp = resetToken
    )
    // Password reset successful
    showMessage("Password reset successfully. You can now sign in.")
    navigateToSignIn()
} catch (e: InsforgeHttpException) {
    Log.e("Auth", "Password reset failed: ${e.message}")
}

Manejo de errores

import dev.insforge.exceptions.InsforgeHttpException
import dev.insforge.exceptions.InsforgeException

try {
    val result = client.auth.signIn(email, password)
} catch (e: InsforgeHttpException) {
    // HTTP errors from API with error codes
    when (e.error) {
        "INVALID_CREDENTIALS" -> showError("Invalid email or password")
        "USER_NOT_FOUND" -> showError("User not found")
        "EMAIL_NOT_VERIFIED" -> showError("Please verify your email")
        "INVALID_EMAIL" -> showError("Invalid email format")
        "WEAK_PASSWORD" -> showError("Password is too weak")
        else -> showError("Error: ${e.message}")
    }
} catch (e: InsforgeException) {
    // Other SDK errors (network, parsing, etc.)
    showError("Error: ${e.message}")
}

Códigos de error comunes

Código de error	Descripción
`INVALID_CREDENTIALS`	El correo electrónico o la contraseña son incorrectos
`USER_NOT_FOUND`	No existe ningún usuario con este correo electrónico
`EMAIL_NOT_VERIFIED`	Verificación de correo electrónico requerida
`INVALID_EMAIL`	Formato de correo electrónico no válido
`WEAK_PASSWORD`	La contraseña no cumple los requisitos
`USER_ALREADY_EXISTS`	El correo electrónico ya está registrado
`SESSION_EXPIRED`	La sesión ha caducado, es necesario reiniciar sesión

​Instalación

​Android Initialization

​signUp()

​Parámetros

​Devuelve

​SignUpResponse

​Ejemplo (Flujo completo con verificación)

​Verificación de correo electrónico

​Métodos relacionados

​signIn()

​Ejemplo

​Verificación de correo electrónico

​signOut()

​Ejemplo

​signInWithOAuthPage()

​Proveedores admitidos

​Parámetros

​Devuelve

​Ejemplo

​getCurrentUser()

​Devuelve

​Ejemplo

​updateProfile()

​Parámetros

​Devuelve

​Ejemplo

​Restablecimiento de contraseña

​sendPasswordReset()

​Parámetros

​Ejemplo

​exchangeResetPasswordToken()

​Parámetros

​Devuelve

​ResetTokenResponse

​Ejemplo

​resetPassword()

​Parámetros

​Ejemplo

​Manejo de errores

​Códigos de error comunes

Instalación

Android Initialization

signUp()

Parámetros

Devuelve

SignUpResponse

Ejemplo (Flujo completo con verificación)

Verificación de correo electrónico

Métodos relacionados

signIn()

Ejemplo

Verificación de correo electrónico

signOut()

Ejemplo

signInWithOAuthPage()

Proveedores admitidos

Parámetros

Devuelve

Ejemplo

getCurrentUser()

Devuelve

Ejemplo

updateProfile()

Parámetros

Devuelve

Ejemplo

Restablecimiento de contraseña

sendPasswordReset()

Parámetros

Ejemplo

exchangeResetPasswordToken()

Parámetros

Devuelve

ResetTokenResponse

Ejemplo

resetPassword()

Parámetros

Ejemplo

Manejo de errores

Códigos de error comunes