Auth0 Android SDK

The following resources are available for integrating and using the Auth0 Android SDK:

• Quickstart Guide: Auth0 Android Quickstart
• Sample Application: Auth0 Android Sample App (Kotlin)
• FAQs: Auth0 Android FAQ
• Examples: Auth0 Android Examples
• API Reference: Javadoc Documentation
• Migration Guide: V4 Migration Guide

The SDK supports both Kotlin and Java consumers. Adding a suspend function as a public method will break compatibility for Java users, as they cannot call coroutine-based methods directly.

Requirement: Every new asynchronous public method must provide both a suspend form (for Kotlin) and a callback form (for Java). Always verify interoperability by writing a Java test.

The BiometricPolicy determines how often a user must re-authenticate to access credentials.

Policy Types:

• BiometricPolicy.Always: Requires authentication every single time credentials are accessed (Default).
• BiometricPolicy.Session(timeoutInSeconds): Requires authentication only if the specified timeout has passed since the last successful authentication.
• BiometricPolicy.AppLifecycle(timeoutInSeconds): Persists the authentication session for the lifetime of the app process. The default timeout is 1 hour (3600 seconds).

// Session policy: 5 minutes
val sessionPolicy = LocalAuthenticationOptions.Builder()
    .setPolicy(BiometricPolicy.Session(300))
    .build()

// App lifecycle policy: 1 hour default
val appLifecyclePolicy = LocalAuthenticationOptions.Builder()
    .setPolicy(BiometricPolicy.AppLifecycle())
    .build()

Management API support (including UsersAPIClient, ManagementException, and ManagementCallback) has been removed from the mobile SDK.

Migration Strategy: Instead of calling the Management API directly from your mobile app, you should:

1. Create a dedicated endpoint on your own backend (e.g., PATCH /me/metadata).
2. Call that endpoint from your app, passing the user's access token as a Bearer token in the Authorization header.
3. On your backend, use a machine-to-machine token (via Client Credentials flow) to call the Auth0 Management API with the required scopes.

The SDK provides two ways to consume asynchronous public methods to support both Kotlin Coroutines and Java consumers:

1. Callback-based: For Java compatibility and standard callback patterns.
2. Suspend functions: For idiomatic Kotlin Coroutine usage.

When interacting with the SDK, choose the pattern that matches your language/concurrency model.

// ✅ Both forms are provided for async public methods
fun getCredentials(callback: Callback<Credentials, CredentialsManagerException>)
suspend fun awaitCredentials(): Credentials

When handling errors from the Auth0.Android SDK, you should use the provided exception hierarchy rather than catching generic Exception or RuntimeException types. This ensures type safety and prevents brittle code based on string matching error messages.

The hierarchy is structured as follows:

• Auth0Exception (Base class)
  • AuthenticationException
  • CredentialsManagerException
  • DPoPException
  • MyAccountException

The CredentialsManager class provides a high-level way to manage user credentials, including checking for existence, storing them, retrieving them, and handling automatic token refreshing.

To enable automatic refreshing when tokens expire, you must include the offline_access scope during the login process to ensure a refresh_token is received.

Key Requirements for Saving Credentials:

• The Credentials object must contain an expires_at value.
• The Credentials object must contain at least an access_token or an id_token.
• If these values are missing, saveCredentials will throw a CredentialsManagerException.

val authentication = AuthenticationAPIClient(account)
val storage = SharedPreferencesStorage(this)
val manager = CredentialsManager(authentication, storage)

Auth0 can include a session_expiry claim in the ID token, which acts as an absolute ceiling (in Unix seconds) for how long a local session can live. This ceiling is independent of access token expiry and cannot be extended by refresh token renewal.

Behavior:

• The ceiling is persisted from the ID token at login.
• On every getCredentials call, if the ceiling is reached, the stored credentials are cleared and the call fails with CredentialsManagerException.SESSION_EXPIRED.
• A ~30-second clock-skew leeway is applied.

Important Implementation Note: The session_expiry value must be in Unix seconds. If you provide a millisecond-magnitude value (e.g., 1700000000000), the SDK will treat it as having no ceiling. Always divide millisecond timestamps by 1000 when emitting this claim from an Auth0 Action.

The Auth0 SDK allows you to customize how network requests are made by providing a NetworkingClient to the Auth0 instance. You can use the DefaultClient.Builder to configure common settings like timeouts, logging, and headers, or provide a custom implementation of the NetworkingClient interface for advanced needs like proxy support or reusing an existing networking stack.

val account = Auth0.getInstance("{YOUR_CLIENT_ID}", "{YOUR_DOMAIN}")
account.networkingClient = netClient