Overview

Relevant source files

• .version
• CHANGELOG.md
• README.md
• auth0/src/test/java/com/auth0/android/Auth0Test.java

This page provides a high-level introduction to the Auth0.Android SDK, including its purpose, main capabilities, and core components. For detailed architectural information, see Architecture Overview. For installation and setup instructions, see Getting Started.

Purpose and Scope

Auth0.Android is an Android SDK that provides authentication and authorization capabilities for Android applications. It enables developers to integrate Auth0's identity platform into their Android apps through a comprehensive set of APIs for:

• Browser-based authentication using Auth0's Universal Login
• Direct API authentication (database, passwordless, MFA, passkeys, social providers)
• Secure credential storage and management
• User profile and account management
• Advanced security features (PKCE, DPoP, token verification)

Requirements:

• Android API 31 or later (version 2.9.0 supports API 30 and below)
• Java 8+ bytecode compatibility
• Current version: 3.12.1

Installation:

Sources: README.md1-58

Main Capabilities

Capability	Description	Primary API
Web Authentication	Browser-based login using Auth0 Universal Login with OAuth 2.0 + PKCE	WebAuthProvider
API Authentication	Direct authentication without browser: database login, passwordless, MFA, passkeys, social tokens	AuthenticationAPIClient
Credential Management	Automatic token storage, refresh, and retrieval with optional encryption and biometric protection	CredentialsManager, SecureCredentialsManager
User Management	Profile retrieval, metadata updates, identity linking	UsersAPIClient
Self-Service Management	User-initiated authentication method enrollment (passkeys, phone, email, TOTP)	MyAccountAPIClient
Security Features	PKCE, DPoP token binding, ID token verification, encrypted storage, biometric authentication	Cross-cutting features

Sources: README.md17-476 Diagram 1, Diagram 4

Core Components

Public API Classes

The SDK exposes four main client classes that applications interact with:

WebAuthProvider - Browser-based authentication

• Entry point: Static methods WebAuthProvider.login(account) and WebAuthProvider.logout(account)
• Launches browser for Universal Login, handles OAuth redirect
• Implements authorization code flow with PKCE
• Location: auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt

AuthenticationAPIClient - Direct authentication API

• Constructor: AuthenticationAPIClient(account)
• Provides methods for database login, passwordless, MFA, passkeys, token operations
• Returns Credentials object containing tokens
• Location: auth0/src/main/java/com/auth0/android/authentication/AuthenticationAPIClient.kt

CredentialsManager / SecureCredentialsManager - Token storage

• Constructors: CredentialsManager(authentication, storage) and SecureCredentialsManager(context, authentication, storage)
• Methods: saveCredentials(), getCredentials(), hasValidCredentials(), clearCredentials()
• Automatic token refresh using refresh tokens
• SecureCredentialsManager adds AES/RSA encryption and biometric authentication
• Location: auth0/src/main/java/com/auth0/android/authentication/storage/

MyAccountAPIClient - User self-service

• Constructor: MyAccountAPIClient(account, accessToken)
• Enroll and manage authentication methods (passkeys, phone, email, TOTP)
• Location: auth0/src/main/java/com/auth0/android/myaccount/MyAccountAPIClient.kt

UsersAPIClient - Administrative user management

• Constructor: UsersAPIClient(account, token)
• Profile retrieval, metadata updates, identity linking
• Location: auth0/src/main/java/com/auth0/android/management/UsersAPIClient.kt

Sources: auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt auth0/src/main/java/com/auth0/android/authentication/AuthenticationAPIClient.kt auth0/src/main/java/com/auth0/android/authentication/storage/CredentialsManager.kt auth0/src/main/java/com/auth0/android/myaccount/MyAccountAPIClient.kt auth0/src/main/java/com/auth0/android/management/UsersAPIClient.kt

Configuration Hub

Auth0 - Central configuration object

• Instantiation: Auth0.getInstance(clientId, domain) or Auth0.getInstance(context) (reads from strings.xml)
• Holds client ID, domain, networking configuration
• Required by all API clients
• Location: auth0/src/main/java/com/auth0/android/Auth0.kt

Sources: auth0/src/main/java/com/auth0/android/Auth0.kt README.md69-100

SDK Architecture

The following diagram shows how the main SDK components relate to each other and to the Android platform:

SDK Component Architecture

Key architectural patterns:

1. Configuration Hub: All API clients require an Auth0 instance that holds the client ID, domain, and networking configuration
2. Dual API Styles: Most operations support both callback-based and coroutine-based (suspend) APIs
3. Automatic Token Refresh: Credential managers automatically refresh expired tokens using refresh tokens
4. Protocol Abstraction: Internal components (OAuthManager, PKCE, RequestFactory) handle protocol details
5. Platform Integration: Direct integration with Android features (Custom Tabs for browsers, Credential Manager for passkeys, Keystore for encryption, BiometricPrompt for authentication)

Sources: Diagram 1, auth0/src/main/java/com/auth0/android/ auth0/src/main/java/com/auth0/android/provider/ auth0/src/main/java/com/auth0/android/authentication/

Authentication Flow Overview

The SDK supports multiple authentication flows, each optimized for different use cases:

Authentication Flow Paths

Flow characteristics:

Flow	Entry Point	Security Features	Use Case
Universal Login	WebAuthProvider.login()	OAuth 2.0 + PKCE + State + ID Token Verification	Recommended for most apps, supports all Auth0 features
Database	AuthenticationAPIClient.login()	ID Token Verification, optional DPoP	Direct username/password when browser unavailable
Passwordless	AuthenticationAPIClient.passwordlessWithEmail/SMS()	ID Token Verification	One-time codes via email or SMS
MFA	AuthenticationAPIClient.multifactorChallenge()	Challenge-response, ID Token Verification	Add second factor to database login
Passkey	AuthenticationAPIClient.signupWithPasskey() / signinWithPasskey()	WebAuthn/FIDO2, Android Credential Manager	Phishing-resistant authentication
Social	AuthenticationAPIClient.loginWithNativeSocialToken()	Token exchange, ID Token Verification	Use native provider SDK tokens

Sources: Diagram 2, README.md102-218 auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt auth0/src/main/java/com/auth0/android/authentication/AuthenticationAPIClient.kt

Credential Management System

After successful authentication, the SDK provides credential managers to store, retrieve, and automatically refresh tokens:

Credential Management Flow

Key features:

• Automatic Token Refresh: When getCredentials() detects expired tokens and a refresh token exists, it automatically calls /oauth/token to renew tokens
• Thread Safety: Both managers are thread-safe (after version 2.8.0)
• Biometric Protection: SecureCredentialsManager can require biometric authentication with configurable policies
• Multi-Audience Support: Via getApiCredentials(audience, scope) for managing multiple access tokens with one refresh token
• SSO Support: Via getSsoCredentials() for Native-to-Web SSO scenarios

Sources: Diagram 3, README.md320-476 auth0/src/main/java/com/auth0/android/authentication/storage/CredentialsManager.kt auth0/src/main/java/com/auth0/android/authentication/storage/SecureCredentialsManager.kt

Security Features

The SDK implements multiple security layers throughout the authentication and credential management lifecycle:

Security Feature Matrix

Security implementations:

• PKCE (Proof Key for Code Exchange): Automatically applied to all WebAuthProvider flows, prevents authorization code interception attacks. See PKCE
• DPoP (Demonstrating Proof-of-Possession): Optional feature that binds tokens to device keys, preventing token theft. Enabled via useDPoP(). See DPoP
• ID Token Verification: All ID tokens are cryptographically verified using JWKS, with claim validation (issuer, audience, expiration, nonce). See ID Token Verification
• Encrypted Storage: SecureCredentialsManager uses AES/RSA encryption with keys stored in Android Keystore. See Encryption and Key Management
• Biometric Authentication: Optional biometric prompt before retrieving credentials, with configurable policies. See Biometric Authentication

Sources: Diagram 5, auth0/src/main/java/com/auth0/android/authentication/ auth0/src/main/java/com/auth0/android/provider/ auth0/src/main/java/com/auth0/android/authentication/storage/

API Styles

The SDK provides dual API styles for most operations:

Callback-based API:

Coroutine-based API:

Both styles are functionally equivalent. Coroutine support was added in version 2.8.0. See Coroutines Support for more details.

Sources: README.md142-189 CHANGELOG.md229-233

Common Data Objects

Credentials - Token response object

• Fields: accessToken, idToken, refreshToken, type, expiresAt, scope, user (UserProfile from ID token)
• Returned by all authentication operations
• Location: auth0/src/main/java/com/auth0/android/result/Credentials.kt

AuthenticationException - Error response

• Fields: code, description, statusCode
• Helper methods: isBrowserAppNotAvailable, isCanceled, isNetworkError, isInvalidCredentials, isMultifactorRequired, isPasswordLeaked, etc.
• Location: auth0/src/main/java/com/auth0/android/authentication/AuthenticationException.kt

UserProfile - User information from ID token

• Fields: id, name, email, nickname, pictureURL, createdAt, etc.
• Extracted from ID token or fetched from /userinfo
• Location: auth0/src/main/java/com/auth0/android/result/UserProfile.kt

Sources: auth0/src/main/java/com/auth0/android/result/ auth0/src/main/java/com/auth0/android/authentication/AuthenticationException.kt

Next Steps

• Installation: See Installation and Dependencies for adding the SDK to your project
• Configuration: See SDK Initialization for setting up the Auth0 instance
• Authentication: See Authentication Methods for implementing login flows
• Credential Storage: See Credential Management for storing and managing tokens
• Architecture Details: See Architecture Overview for in-depth architectural information

Sources: README.md17-476