Android: Session Handling

Gravatar for
By Luciano Balmaceda

This tutorial shows you how to let users log in and maintain an active session with Auth0.

Sample Project

Download a sample project specific to this tutorial configured with your Auth0 API Keys.

System Requirements
  • Android Studio 2.3
  • Android SDK 25
  • Emulator - Nexus 5X - Android 6.0
Show requirements

You need the Credentials class to handle users' credentials. The class is composed of these elements:

  • accessToken: Access Token used by the Auth0 API. To learn more, see the Access Token documentation.
  • idToken: Identity Token that proves the identity of the user. To learn more, see the ID Token documentation.
  • refreshToken: Refresh Token that can be used to request new tokens without signing in again. To learn more, see the Refresh Token documentation.
  • tokenType: The type of tokens issued by the server.
  • expiresIn: The number of seconds before the tokens expire.
  • expiresAt: The date when the tokens expire.
  • scope: The scope that was granted to a user. This information is shown only if the granted scope is different than the requested one.

Tokens are objects used to prove your identity against the Auth0 APIs. Read more about them in the tokens documentation.

Before You Start

Before you continue with this tutorial, make sure that you have completed the Login tutorial.

Before you launch the login process, make sure you get a valid Refresh Token in the response. To do that, ask for the offline_access scope. Find the snippet in which you are initializing the WebAuthProvider class. To that snippet, add the line withScope("openid offline_access").

// app/src/main/java/com/auth0/samples/

Auth0 auth0 = new Auth0(this);
    .withAudience(String.format("https://%s/userinfo", getString(R.string.com_auth0_domain)))
    .withScope("openid offline_access")
    .start(LoginActivity.this, webCallback);

Check for Tokens when the Application Starts

Learn about Refresh Tokens

Before you go further with this tutorial, read the refresh token documentation. It is important that you remember the following:

  • Refresh Tokens must be securely saved.
  • Even though Refresh Tokens cannot expire, they can be revoked.
  • New tokens will have the same scope as was originally requested during the first authentication.

You can simplify the way you handle user sessions using a Credential Manager class, which knows how to securely store, retrieve and renew credentials obtained from Auth0. Two classes are provided in the SDK to help you achieve this. Further read on how they work and their implementation differences is available in the Saving and Renewing Tokens article. For this series of tutorials we're going to use the SecureCredentialsManager class as it encrypts the credentials before storing them in a private SharedPreferences file.

Create a new instance of the Credentials Manager. When you run the application, you should check if there are any previously stored credentials. You can use these credentials to bypass the login screen:

// app/src/main/java/com/auth0/samples/
  Auth0 auth0 = new Auth0(this);
  AuthenticationAPIClient client = new AuthenticationAPIClient(auth0);
  SecureCredentialsManager credentialsManager = new SecureCredentialsManager(this, client, new SharedPreferencesStorage(this));

  // Check if the activity was launched after a logout
  if (getIntent().getBooleanExtra(KEY_CLEAR_CREDENTIALS, false)) {

  if (!credentialsManager.hasValidCredentials()) {
    // Prompt Login screen.
  } else {
    // Obtain credentials and move to the next activity

Ideally a single class should manage the handling of credentials. You can share this instance across activities or create a new one every time is required as long as the Storage strategy persists the data in the same location. Check the LoginActivity class to understand how to achieve this in a single class.

Save the User's Credentials

After a successful login response, you can store the user's credentials using the saveCredentials method.

// app/src/main/java/com/auth0/samples/

private final AuthCallback webCallback = new AuthCallback() {
    public void onFailure(@NonNull final Dialog dialog) {
        //show error dialog

    public void onFailure(AuthenticationException exception) {
        //show error message

    public void onSuccess(@NonNull Credentials credentials) {
        //user successfully authenticated

A Storage defines how data is going to be persisted in the device. The Storage implementation given to the Credentials Manager in the seed project uses a SharedPreferences file to store the user credentials in Private mode. You can modify this behavior by implementing a custom Storage.

Recover the User's Credentials

Retrieving the credentials from the Credentials Manager is an async process, as credentials may have expired and require to be refreshed. This renewing process is done automatically by the Credentials Manager as long as a valid Refresh Token is currently stored. A CredentialsManagerException exception will be raised if the credentials cannot be renewed.

// app/src/main/java/com/auth0/samples/

credentialsManager.getCredentials(new BaseCallback<Credentials, CredentialsManagerException>() {
    public void onSuccess(Credentials credentials) {
        // Move to the next activity

    public void onFailure(CredentialsManagerException error) {
        // Credentials could not be refreshed.

The SecureCredentialsManager can prompt the user for local device authentication using the configured Lock Screen (PIN, Password, Pattern, Fingerprint) before giving them the stored credentials. This behavior can be enabled calling the SecureCredentialsManager#requireAuthentication method when setting up the Credentials Manager. The sample has this line commented for convenience, remove the comment to try it.

Log the User Out

To log the user out, you remove their credentials and navigate them to the login screen. When using a Credentials Manager you do that calling clearCredentials.

In the sample, the LoginActivity checks that a boolean extra is present in the Intent at the Activity launch, so that if this flag is true the credentials are first removed from the Credentials Manager.

// app/src/main/java/com/auth0/samples/

private void logout() {
    Intent intent = new Intent(this, LoginActivity.class);
    intent.putExtra(LoginActivity.KEY_CLEAR_CREDENTIALS, true);

// app/src/main/java/com/auth0/samples/
protected void onCreate(Bundle savedInstanceState) {
    if (getIntent().getBooleanExtra(KEY_CLEAR_CREDENTIALS, false)) {

If you are not using our Credentials Manager classes, you are responsible for ensuring that the user's credentials have been removed.

Previous Tutorial
2. Login
Next Tutorial
4. User Profile
Was this article helpful?
Use Auth0 for FREECreate free Account