Update 2/29/16: These code examples have been updated to reflect the 3.0
release of the express-stormpath integration.

When you build a REST API, creating the infrastructure to authenticating access to the API securely with keys, OAuth tokens, and scopes can be tedious, risky and time-consuming. Fortunately, Stormpath just added API authentication to our express-stormpath module. Now, API and webapp developers using express.js can generate and manage API Keys and OAuth tokens as well as lookup and secure developer accounts – all without custom OAuth code.

What We’re Building

This post will walk you through an express application that lets you:

  • Create a new account (register) with email and password.
  • Log into your new account (login) with email and password.
  • Display a dashboard page once you’ve logged in, that is only accessible to registered users.
  • Automatically generate and show an API Key for a logged in user on the dashboard.
  • Make a REST call using Basic authentication.
  • Generate an OAuth token with scope.
  • Make a REST call using Bearer authentication.
  • Allow a logged in user to log out of their account (logout).

The API I built is a simple one: it returns the weather for a requested city in Fahrenheit.

Before We Start…

  1. Follow along with the app online
  2. When you have the application running in a browser, open the “Web Inspector” and navigate to the Network tab to see some important things happening:
    • When making any REST calls on generating OAuth tokens, click on the request made to the /weather endpoint and look at the Request Headers –> Authorization.
    • When generating an OAuth Token, click on the oauth request and scroll down to the section titled “Form Data” to see the grant_type and the scope of the request.
  3. Note the directory structure of the github repository for this project. All server-side logic (which this post focuses on) will be in /server.js.

Let’s get started.


User registration and login are built into express-stormpath, and a good place to start with any app. You can see the login screens on the live app.

Default Login Screen Stormpath Express API Management

Let’s take a look at the code that makes this happen. We first import the necessary packages (all code in this post goes into the root node file, in my case /server.js):

Next, we set up the server to use Stormpath:

The application field points Stormpath to the right application for the project. Users will be pointed to the nextUri after logging in or creating an account. As for the Oauth fields, we will get back to those a little later. It is important to avoid storing your API Key, Application Href, and Secret Keys (used for user sessions) in plain text in your code. Instead, export these as environment variables and access them in server.js by doing process.env['name_of_env_var']. Stormpath-express is capable of reading the environment variables itself, so exporting them to your system is enough; however, above I show how to manually set the stormpath-express variables in code.

Once a user goes to our site (the root of the site or ‘/’), we need to redirect them to the custom login page provided by stormpath-express, which by default lives at /login.

Now that we have login and account creation out of the way, let’s use API Keys to protect our weather API.

API Key Generation

First, we need to give the user an API key to use. This way, any REST endpoint is protected and accessible only to users who possess a valid API Key and Secret. Once a user logs in or creates an account, they will go directly to the application dashboard, where an API Key is automatically generated and displayed.

Dashboard with API Key

Let’s see what the code looks like:

By calling res.locals.user.getApiKeys we ask Stormpath to return a collection of an account’s API Keys. In the if statement, we check if the account has any API Keys. If not, Stormpath generates one and returns it to the client. In the else statement, where an API Key has already been generated, Stormpath returns the first API Key available.

Making a REST Call With Basic Authentication

Now the user is logged in and has access using the API Key Id and Secret. Let’s have them make an API call.

Basic Authentication Dashboard

In this sample application, the REST endpoint returns a floating point number, representing the weather in the requested city. For example if a GET request is made to /weather/London, a floating point number with one digit after the decimal is returned to the client representing the weather in London. Only one endpoint is available in the form of weather/, where city can be any one of the four cities provided by the radio buttons.

First, the client has to Base64 encode the key:secret pair and send this to the server as the authorization header. In angular.js, the HTTP request would look something like this:

In this HTTP request, we specify the desired city in the url: /weather/ and add our Base64 encoded API key as the authorization header.

Now lets take a look at what happens on the server side, where this request gets processed:

First, notice the stormpath.apiAuthenticationRequired call that precedes the callback function of our route. This function verifies that the authorization credentials sent over are legitimate. If they are not, the server will return a 401 Unauthorized error. Assuming the credentials are correct, the server is then allowed to return the weather of the desired city.

Here is how the same request can be made with CURL:

curl –user "[API_KEY]:[API_SECRET]" http://localhost:8080/weather/London

If authentication is successful you will get back a floating point number representing the weather in London. If it is not, you will see: {“error”:“Invalid API credentials.”}.

Generating an OAuth Token with Scope

Basic Authentication is acceptable for a few use cases, but we strongly recommend you use OAuth if security is important to your API. By using OAuth, making requests to protected endpoints does not expose the API Key Id and Secret. It also gives a developer the ability to only give access to certain scopes of the endpoint the user is trying to access. This is compared to authenticating with API keys, which gives access to the entire endpoint.

Generate OAuth Token with Scope

By checking the desired cities and clicking Get Oauth, the user gets a token which can now be used to target the REST endpoint. What exactly happened on the server side to generate this Oauth Token? Let’s look at the server setup code one more time:

With this, a POST request sent to that URL will check for API Key credentials and return a Token that is valid for 1 hour (by default). This POST request also needs to have a form parameter “grant_type” with the value set as the requested scope. Here is the request in angular.js:

Making a REST Call Using the OAuth Token

In order to hit the REST endpoint using Oauth, we must send our token to the weather/ endpoint using Bearer authentication:

Now, on the server side we can add the logic for Bearer authentication, and parse our requested scopes.

The requested scopes live inside the res.locals.permissions object and we can search it to see if the city we want the weather for is permitted for us. If so, the server will proceed to return the weather; if not, a 403 is returned. Compared to a 401 error, which is stands for an unauthorized request, a 403 represents a forbidden request.

London was part of the scopes in the Oauth Token so getting its weather is no problem:

Set Scope for OAuth Token Example

Berlin on the other hand was not, so the weather is not given and an error is returned instead:

API scope permission denied


Node.js and the express-stormpath package make it easy to generate and manage API Key-based authentication in your webapp or API. If you’d like to see more code and even run this application yourself, check out the source code and let us know what you think!