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

Stormpath provides authentication tools for APIs, so we work closely with devs building new REST services. We also hear a lot about the challenges that come with building an API. Billing is often high on that list of pitfalls. While charging users has long been a complicated issue, it can also be surprisingly painless for many use cases. We’ll show you how!

In this tutorial, I’ll run through how to:

  • Prop up a simple web console where your API users can register, login, get a Key for your REST API, and update their Account to a paid plan
  • Setup a monthly subscription plan and email users with monthly invoices
  • Securely collect credit card data and charge a recurring fee
  • Store unique billing info on your user records
  • Expose a simple REST endpoint, secured with HTTP basic authentication
  • Limit access to that endpoint to paying users only
  • Revoke API access when a user unsubscribes or fails to pay an invoice

This tutorial should take less than half an hour to run through. We’ll use Stormpath for user management and API Key Management and Stripe for all things billing related. We’re also running Node.js + Express.js, but the steps are the same no matter your stack. Leave a comment or email [email protected] if you have questions on using this guide in your app.

Scaffolding for this project is based on an earlier blog on writing a full-fledged API service. It’s a great resource for in-depth code explanations, as I’ll focus mostly on billing aspects here.

Set Up Your User Store – Stormpath

To get started, register for a free Stormpath developer account. Stormpath is an authentication and user management service that stores your user accounts and exposes a host of endpoints for working with those users. Sign up here, click the verification link in your Email and login into the admin console here.

Once you’re in, download your Stormpath API Key (located under the “Developer Tools” section on the homepage). You will need the values in the apiKey.properties file to test your work.

Next, create a Stormpath Application to represent this sample project. Stormpath Applications are convenience resources to help you model out your user data; create one for every real-world app backed by Stormpath. Go ahead and click on “Applications” in the navigation bar, hit the blue “Create Application” button and keep the settings default in the subsequent popup. Name the Application whatever you want, but something like “Sample Billing API” would work nicely! Once created, take note of the Application’s REST URL because we’ll need it too.

Stormpath Create new app

As a last step, let’s turn on email verification. To do so, click the “Directories” tab and find the Directory auto-generated for the new Application (e.g. “Sample Billing API Directory”). Once on the page for this Directory, click the “Workflows” link on the left-hand sidebar and you will find yourself looking at the Email verification workflow page.

Stormpath configure Directory

Make three changes on this page: Update the drop down value to “enabled”, set the “Link Base URL” to http://localhost:3000/verified and click the blue “Save Changes” button. Optionally, update the wording of the email to whatever you like, so long as you include the ${url} macro.

Now that this workflow is enabled, all new Accounts will be created with an unverified status in Stormpath and will not be allowed to authenticate until they click the email sent to them on registration. This type of verification step is generally just a good practice for any sort of secure app, but it’s a requirement for us because we are going to use the email address users give us on registration to create a customer record for them. Knowing that every user actually has access to the email address they register with is therefore that much more important.

Setup Your Billing Provider – Stripe

We have one more service provider to register for: Stripe. Stripe manages credit card data, subscriptions and payment transactions, so we don’t have to worry about things like PCI compliance, or building a billing backend.

Once registered, you’ll notice that your Stripe Account is set to “test”. Leave that setting alone as it will allow us to use test credit cards when we’re ready.

Hold off on further Stripe configurations for now; just make sure to take note of your Stripe API Keys. More specifically, your pair of test Keys. You can find them in your account page under the “API Keys” tab.

Stripe API Keys

Write the Web Console and REST API

All of the code for this project is available on GitHub. To follow along directly, pull down the repo and cd into the project folder. Once downloaded, install the Node.js dependencies by running npm install from your terminal which will automatically pull what you need from the package.json file. Assuming you have Node.js and NPM installed of course =).

Next, run bower install to get the frontend dependencies via the bower.json file.

Our basic web console should have a few key functions right away:

  1. It can securely register users with a username and password securely
  2. It can consume verification tokens to enable newly created users after they click through the verification email
  3. It can log in users to a basic dashboard page and create a secure session

The core functionality of our app is wrapped up in the index.js file. Here, we import our libraries and routes:

Create the Express.js application:

Specify a templating engine:

Configure API access to Stripe:

Configure middleware to serve static files:

Configure Stormpath’s Express.js integration:

Specify route code:

And finally, prop up our server.

To illustrate further, let’s take a quick look at the views routes.


As you can see, there are only two public pages we absolutely need: A homepage for our app and a pricing page so we can tell new users how much API access will cost them. And why it’s totally worth the cost.


For now, private.js just needs to serve up our dashboard.jade template. You may be wondering why there are no routes related to auth. The answer is Express-Stormpath takes care of all the basic authentication functionality (including views) like registration, login, and email verification, all out of the box.

However, to make Express-Stormpath work the way we want it to, there are three important configurations to set in index.js:

  1. First, set enableAccountVerification to true so the library knows to expect an enabled verification workflow.
  2. Second, tell Express-Stormpath to redirect to /dashboard after registration and login.
  3. Lastly, pass in a long, randomly-generated secret to encrypt sessions.

We’re just missing one key piece of functionality… our money maker! Inside the routes directory, add one more file: api.js. My API has just one endpoint, /hi that greets API consumers with a friendly message.

Generate API Keys for Your Users with Stormpath

If you plan to charge for your API, you also want to secure it with proper authentication. This means username and password aren’t going to cut it and your app needs to generate a unique set of high entropy API Keys for each user, just as Stripe and Stormpath did when we registered earlier.

Express-Stormpath can do this step automatically on every registration by defining a custom [post registration handler]http://docs.stormpath.com/nodejs/express/latest/registration.html#post-registration-handler):

Once the keys are generated, it’s a quick job to expose them to the user in the dashboard. Add a section to display the API Key and ID like so:

And there you have it! Your users can register, verify they are who they say they are, find their API credentials and use them to hit your awesome new REST endpoint.

Add Billing to Your API

Return to the Stripe dashboard to continue setting up your account, starting by creating a new plan. This is where you get to determine what a subscription to your API looks like. Here’s mine for reference, but be sure to play with the details!

Create Stripe Plan

For this sample, I only need one plan (only one endpoint after all), but it’s entirely possible to create more.

At this point, I want to briefly acknowledge that monthly subscriptions are far from the only billing model out there. They are simply what most of our users here at Stormpath are implementing and mesh with the overall trend to a SaaS-based world. Still, a better option for some APIs is going to be a charge-per-query model as seen here. Fortunately for all of us, Stripe supports both.

Now that the plan is ready in Stripe, add a form to your own dashboard to collect a user’s credit card data and POST it to Stripe. The easiest way to do that is with Stripe checkout. Here’s how that might look in our dashboard template:

However, that’s actually only half the battle. Because this form lives on the client side, what it actually does is create a token. This token is then passed to a private route (/charge) that will POST it to Stripe with instructions on what sort of action we want to take.

In our case, we want to do three things:

  1. Create the customer in Stripe and add them to our Plan
  2. In a callback, save the user’s new Stripe customer ID to their Stormpath Account record
  3. Save information about the plan to the user’s Stormpath Account record

At a high level, the function uses the session Express-Stormpath created (req.user) on authentication to find and update the correct Account. More specifically, it’s saving data (from Stripe) to the Account’s customData; a schemaless JSON resource available on all Stormpath Accounts. customData can store whatever user data you want in Stormpath and that means we don’t have to spin up a database =).

I chose to call the two new customData keys billingProviderId and billingTier, but you can use whatever JSON compatible values you like.

Implement Authorization in Your API

At this point, the user can register, connect to your API securely, and pay you. However, there’s one more thing to do: restrict access to the API to paying users only. We can’t be greeting freeloaders after all!

Commonly referred to as authorization, the API needs to check who the caller is, what plan they are on and whether they should have access to the endpoint. The first element, knowing who they are, has already been implemented via HTTP Basic Auth.

With the user identified, verify that their plan matches what it should. Here’s our basic authorization check on the updated api/hi route:

In a production app, you would want to decouple the authorization check into middleware, but hopefully this helps illustrate how simple the logic is. api/hi is officially available to paid users only.

Run Your API Service – with Billing!

Of course, you’ll want to check that everything is working as expected! Remember all those Stripe and Stormpath credentials you collected in the beginning? Now is the time to expose them to your application as environment variables.

Run the application with: node index.js and visit the index page in your browser at http://localhost:3000 where you should be greeted with:

Billing App Homepage

You can now check out the pricing page, be thoroughly convinced, and register for the app. Once logged in, you should see a set of API credentials for your API. Use these to make a test request against your api with cURL:

If all is well, your API should return a HTTP 402 error response with a message telling you to upgrade.

Go back into the dashboard and click the Upgrade button. Because Stripe is in test mode, use 4242 4242 4242 4242 for the card number, any future date for the expiration field and a random 3 digits for the cvc.

To verify that the transaction went through, try running the exact same cURL command again. Congratulations! You now have a fully functional web console and REST API with billing built-in and enforced.

Optional Configurations

There are a nearly unlimited number of things you could do to improve this rather paltry API. Here are three to consider.

Revoke Access When a User Fails to Pay

Once your service blows up in popularity, it will become increasingly annoying to manually update every Account that stops paying. Stripe webhooks are a great way to automate this process. In our case, we want to setup a webhook that fires off whenever a customer’s subscription is deleted.

Stripe Webhook

Once the webhook is configured in Stripe, expose a public route to consume the event. Due to the nature of webhooks, we can’t simply trust that Stripe was the one to hit our endpoint so there are a few additional steps we need to take to be on the secure side:

  1. Consume the webhook from Stripe and parse out the event ID
  2. POST back to Stripe using the event ID and check that the event matches the type we expect
  3. Retrieve the customer associated with the event and parse out their Email
  4. Search Stormpath for the Account associated with that Email address
  5. Update the Account to reflect their new subscription status
  6. Respond to Stripe to indicate the webhook was successfully received

Here’s how that looks:

To test, expose your local server to the internet so Stripe’s webhook can hit the new route. Ngrok is a great option for that. Once running, update the Stripe webhook to point at your public ngrok URL and cancel a test customer’s subscription. If successful, you should see an update on their Stormpath Account’s customData to reflect the cancellation.

Configure Stripe to Send Invoice Receipts via Email

This may not seem like a big deal, but trust us, it is super convenient for you and your customers! The Stormpath billing team fully endorses this option =). Enable it in Stripe’s Account Settings Email tab.

Stripe Email configurations

Add Paid Users to a Stormpath Group

I chose to use customData for authorization in my example because its flexibility would allow me to implement very granular authorization rules based on the plan data collected from Stripe. However, Stormpath does support the notion of a Group that’s more commonly used used for authorization. The Group approach is handy because it is very simple to query against Stormpath for all users that belong to a particular Group.

To get the best of both worlds, create a new Group to represent the Stripe plan in Stormpath and add users to it when they upgrade. To create the Group, log into the Stormpath admin console, find your Directory, Click ‘Groups’ in the sidebar and click the ‘Create Group’ button.

Stormpath create Group

Now update /charge to additionally add the user to a Group:

Other Resources on API Authentication

And that’s a wrap! Feedback and questions are most welcome in the comments, and you can always email [email protected] for answers and assistance.