Auth0 Android Integration

com.auth0.android:auth0

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

gh api repos/auth0/Auth0.Android/releases/latest --jq '.tag_name'

Use the returned version in all

implementation

dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/Auth0.Android/releases.

Prerequisites

• Android API 21 or higher
• Kotlin or Java project
• Auth0 account with a Native application configured
• If you don't have Auth0 set up, see auth0-quickstart

When NOT to Use

• React Native apps: Use auth0-react-native
• Flutter apps: Use the native Flutter Auth0 SDK
• Web SPAs (React, Angular, Vue): Use auth0-react, auth0-angular, or auth0-vue
• Node.js/Express servers: Use auth0-express
• iOS/macOS apps: Use auth0-swift

Quick Start Workflow

1. Install SDK: Add the Auth0 Android SDK dependency to your

   build.gradle

   :
   gradle

   implementation 'com.auth0.android:auth0:{LATEST_VERSION}'

2. Configure Auth0:

   Agent instruction: Check whether the user prompt already includes both Auth0 Client ID and Domain.

   • If both are provided, proceed directly to Manual Setup in Setup Guide using those values.
   • If either is missing, you MUST ask the user BEFORE writing any code or files:
     • Question: "How would you like to configure Auth0 for this project?"
     • Options: "Automatic setup (Recommended) — Auth0 CLI creates the app and writes credentials to strings.xml" / "Manual setup — I'll provide my Client ID and Domain"

   Then follow Setup Guide for the chosen path. Do NOT proceed to step 3 until Auth0 credentials are confirmed.

   Note: For native Android apps, Domain and Client ID are public configuration (not secrets). No client secret is used. Write values directly to

   strings.xml

   without displaying them in conversation output.

3. Initialize: Create an Auth0 account instance:
   kotlin

   import com.auth0.android.Auth0
   
   val account = Auth0.getInstance(context)

4. Add Auth UI: Implement login and logout with Web Auth:

   Agent instruction: Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons (e.g.,

   loginButton

   ,

   signInButton

   ,

   logoutButton

   ,

   signOutButton

   , or

   setOnClickListener

   with auth-related naming). If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.

   Login:
   kotlin

   import com.auth0.android.Auth0
   import com.auth0.android.authentication.AuthenticationAPIClient
   import com.auth0.android.authentication.storage.SecureCredentialsManager
   import com.auth0.android.authentication.storage.SharedPreferencesStorage
   import com.auth0.android.callback.Callback
   import com.auth0.android.authentication.AuthenticationException
   import com.auth0.android.provider.WebAuthProvider
   import com.auth0.android.result.Credentials
   
   val account = Auth0.getInstance(context)
   val authentication = AuthenticationAPIClient(account)
   val storage = SharedPreferencesStorage(context)
   val credentialsManager = SecureCredentialsManager(context, authentication, storage)
   
   WebAuthProvider.login(account)
       .withScheme(getString(R.string.com_auth0_scheme))
       .withScope("openid profile email offline_access")
       .start(this, object : Callback<Credentials, AuthenticationException> {
           override fun onSuccess(result: Credentials) {
               // User authenticated
               val idToken = result.idToken
               val accessToken = result.accessToken
               // Store credentials securely
               credentialsManager.saveCredentials(result)
           }
           override fun onFailure(error: AuthenticationException) {
               // Handle authentication failure
               Log.e("Auth0", "Authentication failed", error)
           }
       })

   Logout:
   kotlin

   WebAuthProvider.logout(account)
       .withScheme(getString(R.string.com_auth0_scheme))
       .start(this, object : Callback<Void?, AuthenticationException> {
           override fun onSuccess(result: Void) {
               // User logged out
           }
           override fun onFailure(error: AuthenticationException) {
               Log.e("Auth0", "Logout failed", error)
           }
       })

5. Build & Verify:

   Agent instruction: After completing the integration, build the project to verify it compiles successfully:

   bash

   ./gradlew assembleDebug

   If the build fails, analyze the error output and fix the issues. Common integration build failures include:

   • Unresolved reference: Missing import statements — add the required

     import com.auth0.android.*

     imports
   • Cannot resolve symbol

     R.string.com_auth0_scheme

     :

     strings.xml

     not updated — verify

     com_auth0_scheme

     ,

     com_auth0_client_id

     , and

     com_auth0_domain

     entries exist
   • Incompatible types in callback: Callback type parameters don't match — ensure

     Callback<Credentials, AuthenticationException>

     for login and

     Callback<Void?, AuthenticationException>

     for logout
   • Unresolved

     lifecycleScope

     : Missing dependency — add

     implementation 'androidx.lifecycle:lifecycle-runtime-ktx:2.6.+'

     or move code out of coroutine scope
   • minSdk too low: SDK requires API 21+ — update

     minSdkVersion

     to at least 21
   • Java version mismatch: SDK requires Java 8 — add

     compileOptions

     with

     JavaVersion.VERSION_1_8

   Re-run the build after each fix. Track the number of build-fix iterations.

   Failcheck: If the build still fails after 5–6 fix attempts, stop and ask the user:

   • Question: "The build is still failing after several fix attempts. How would you like to proceed?"
   • Options: "Let the agent continue fixing iteratively" / "I'll fix it manually — show me the errors" / "Skip build verification and proceed"

   Repeat this check after every 5–6 iterations if errors persist. Do not leave the project in a non-compiling state without the user's explicit consent.

   The callback URL must match your Auth0 application settings:

   {SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback

Detailed Documentation

• Setup Guide — Install SDK, configure Auth0 application, set up callback URLs, Android App Links, custom schemes, ProGuard/R8
• Integration Patterns — Web Auth login/logout, credential storage, biometric authentication, database login, passwordless authentication, MFA handling, custom tabs, error handling
• Testing & Reference — Testing checklist, common issues, security considerations, API reference

Common Mistakes

{SCHEME}://{YOUR_AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback

{SCHEME}

com_auth0_scheme

strings.xml

demo

<uses-permission android:name="android.permission.INTERNET" />

AndroidManifest.xml

https

myapp://callback

.validateClaims()

.validateClaims()

AuthenticationAPIClient

SecureCredentialsManager

manifestPlaceholders = [auth0Domain: "@string/com_auth0_domain", auth0Scheme: "@string/com_auth0_scheme"]

build.gradle

defaultConfig

Related Skills

• auth0-quickstart — Set up an Auth0 account and application
• auth0-mfa — Configure multi-factor authentication
• auth0-swift — iOS/macOS authentication
• auth0-cli — Manage Auth0 resources from the terminal

Quick Reference

Core Classes

Auth0

WebAuthProvider

AuthenticationAPIClient

SecureCredentialsManager

Credentials

Common Use Cases

• Log in with Web Auth
• Log out
• Store credentials securely
• Require biometric authentication
• Database login
• Passwordless authentication
• Handle MFA
• Call protected APIs

References

• Auth0 Android SDK Documentation
• Auth0 Android GitHub Repository
• Android SDK Javadoc
• Auth0 Android Quickstart
• Sample App