In this tutorial, we will build a simple Android app that stores user generated notes remotely, with user authentication managed by Stormpath and our new Android SDK. This tutorial will take about 15 minutes, and will demonstrate how easy and seamless it is to integrate Stormpath into new and existing Android applications, as well as cover some security and performance issues in Android development.

Android Demo

Why Stormpath for Android Applications?

Stormpath is an authentication service that securely stores your user accounts and private user information. Plus, it’s free to use for small projects!

Having an authentication service like Stormpath allows you to build secure mobile applications that can register and login users in a variety of ways, without compromising your device security.

Using Stormpath, users are logged in securely using the OAuth2 protocol with signed JSON Web Tokens.

Network Service Diagram

With Stormpath, you don’t need to be an expert in cryptography to create a trusted front door to your application. In the context of this tutorial, the “User” is on the client side mobile app, and the “Application” is the server hosted on Heroku.

Using the Stormpath Android library makes it simple to implement user authentication correctly, as opposed to spending lots of time and effort building secure authentication methods into your next mobile app!

The Stormpath Android library can also be used to help build more complex authentication scenarios, such as multi-tenancy and single sign on.

In network-driven mobile apps, implementing authentication incorrectly can be an enormous risk to your users, and cause lots of wasted time and development effort fixing bugs that should never have been introduced.

Getting a proper authentication library implemented into your mobile app codebase early on is a great way to speed up development and reduce frustration later on.

OK! Let’s Build Something!

Let’s build a simple note-taking application in Android. By the end of this tutorial you will have an app that allows you to register and login as a user, save a note, and retrieve that note from your server. Literally, synchronize your note data with a cloud backend!

This tutorial is for Android apps written in Java and the Android SDK. If you aren’t hip enough to write code that works on 2,300 different devices, there is an iOS tutorial written in Swift as well >:)

Setting up Our Android Project

In this tutorial, we’ve done all of the backend work for you, and the API server is hosted at

A typical Stormpath integration primarily involves your API server architecture communicating with Stormpath’s backend service. This allows you to keep your Stormpath API keys on your server instead of hard-coded in your mobile app.

To integrate with your existing backend (instead of our example one), take some time to look at our language specific server side tutorials. Or — just shoot that link to your backend team =)

The backend API service we’re using exposes two protected endpoints for your Android application to use:

  • GET /notes – Returns the notes for the authenticated user in the form of a JSON object.
  • POST /notes – Takes a JSON object with the notes and saves it for the authenticated user.

The JSON object is always in the form of:

In case you’re curious, we used the following tools to build the backend for Stormpath Notes:

  • Express – A Node.js framework that makes it easy to build API services.
  • Express-Stormpath – Exposes a configurable REST API for our mobile clients within Express.
  • Stormpath – Allows us to store and authenticate users without having to create our own backend for it.
  • Heroku – Hosts the code for Stormpath Notes online.

Installing Stormpath

If you’d like to see the finished version of the project, check out the finished branch.

Create The “Notes” Android Application

Open the project using Android Studio and it should be configured to compile.

The Gradle dependency for including the Stormpath SDK is:

In the Application class (, add the following in the onCreate method:

Optionally, for debug information, add this method before StormpathConfiguration‘s method calls.

User Login and Registration Flow

This project includes the Java classes for pre-built Stormpath login. These files are also included in the Stormpath SDK-UI library as configurable login UI, which is distinct from the SDK classes. If you want your own custom user experience, the Stormpath.login network method can be used without the view controls.

These SDK-UI classes authenticate using the Stormpath SDK to a server running Stormpath dependences.

StormpathLoginActivity can be started with:

In there are a few instances where the StormpathLoginActivity will need to be revealed.

Within the onResume method, we can check if there is a user logged by grabbing the user profile. If there isn’t one, show the Login, otherwise, retrieve the note.

Look at the private methods getNotes() and saveNote() for examples of OkHttp3 method preparation.

The way both of these methods work is that they form the request, add headers, make the network call, and broadcast to another part of the app on a successful response from the network.

Both of these methods require the Headers object to be prepared properly for authentication. buildStandardHeaders() does this for you:

Within the Stormpath database, the Notes key/value pair is stored within the user’s “CustomData” field. Although arbitrary key/value pairs can be added to the User’s object, Stormpath is not intended to used as arbitrary object storage.

saveNotes() is called within the FloatingActionButton‘s onClickListener

Finally, let’s add a logout method in the Toolbar’s menu. In onOptionsItemSelected find the if statement regarding (id == and add the following:

Now the user will be able to logout, and will immediately be presented with the Login flow.

An optional addition would be saving the notes client side.

Now compile and run! If you now run and try out your app again, you’ll find that you can now register users, log in, and save your notes!

What’s Next?

Try the iOS SDK – If you (or a friend) is into iOS development, try following through the iOS tutorial for Stormpath Notes. Since the app will make requests against the same API, you’ll notice that you can save your notes on one device, and open them up on the other!

Build a Backend with Stormpath – Try building this API from scratch! Stormpath Notes’ example backend is just 45 lines of code! See code on GitHub. Alternatively, try getting started with express-stormpath or stormpath-laravel (more integrations coming soon!)

Stormpath is free to use, and can help your team write a secure, scalable application without worrying about the nitty-gritty details of authentication, authorization, and user security. Sign up for an account today!

Android is a trademark of Google Inc.

The Android robot is reproduced or modified from work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License.

  • Mary

    Thanks for the tutorial! My only issue was that I kept receiving an error when I put this bit in onCreate.

    Stormpath.getUserProfile(new StormpathCallback() {
    public void onSuccess(UserProfile userProfile) {

    @Override public void onFailure(StormpathError error) {
    // Show login view again.
    startActivity(new Intent(context, StormpathLoginActivity.class));

    The error said that there was an unchecked assignment from an anonymous object to type UserProfile.

    However it worked when I replaced that code fragment with:

    new StormpathCallback() {

    I’m using compile ‘com.stormpath.sdk:stormpath-sdk-android:1.0.2’ as a dependency, so that might be where the issue emerged from.

    • Thanks Mary! I’ll take a look into this and update the blog article when I get a chance =]

      • Hey Mary, sorry about this — must have slipped my task list =] But I’ve gotten it resolved now! Check out the new tutorial content for how to do things =]

  • James Grunewald

    Is there a way you can post the working example with the code in this tutorial on the GitHub repo? I’m not an android expert, but I’m getting a lot of little issues and I’m trying to figure out if I’m adding this code bits correctly, but there’s nothing to compare it to.

  • FLBKernel

    Hi guys, First of all I want to thanks for this great tutorial. If I am able to solve my problem, Stormpath would be key tool for my Master’s final project.
    I am getting this error when I run android app: “java.lang.IllegalStateException: You need to initialize Stormpath before using it. To do that call Stormpath.init() with a valid configuration.” at the line 92 where I’m calling this methods:
    Stormpath.getUserProfile(new StormpathCallback() {


    public void onSuccess(Object o) {


    @Override public void onFailure(StormpathError error) {

    // Show login view again.


    startActivity(new Intent(context, StormpathLoginActivity.class));



    Stormpath.init() it is supposed to be called in the class but apparently is not.
    Any idea please?


  • FLBKernel

    I have solved the problem I mentioned before. Everything works as expected except one thing. Once I Log in with a registered user (i.e. [email protected]) it logs in successfully but it shows login screen from stormpath sdk again instead of the note’s editor.
    I’ve checked and confirmed that it logs in properly and it retrieves JSON object with the content of the notes properly too.

    Any idea please?

    • Hey FLBKernel,

      I took a look through the code and fixed the bug =] Try the tutorial again; it should work properly now!

      • FLBKernel

        Thanks Edward, now it works as expected 🙂 Great tutorial!