3scale API Management

This add-on is operated by 3scale, Inc.

Add access control, analytics and developer provisioning to your API.

3scale API Management

Last Updated: 07 May 2015

Table of Contents

3scale is an add-on to add authorization, rate limiting, developer sign-up, usage analytics and other API management features to your API.

Adding 3scale to an application provides:

  • Access control: open your API to the world in a secure and controlled manner. Easily and visually configure access to your API resources for each type of user.
  • API analytics: gain instant insight into your API activity. Get detailed traffic analytics and reports by account or endpoint. Also provider your partners and developers with their traffic reports.
  • Developer portal: Control the provisioning of developer accounts through a completely customizable portal. Automate key provisioning and engage with your developer community.
  • Manage the lifecycle of your API: Easily add, maintain, update and deprecate API products.
  • API documentation: Publish interactive documentation to ease the learning curve for developers using your API.

3scale is accessible via an API and has supported client libraries for Ruby, Java, Node.js, Python, PHP and Perl.

Provisioning the add-on

3scale can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:create threescale
-----> Adding threescale to sharp-mountain-4005... done, v18 (free)

Even if you can use this add-on for free, your Heroku account needs to be verified by adding your credit card details in order to use any third party add-on. You can read here about the steps to verify your account.

Once 3scale has been added a THREESCALE_PROVIDER_KEY setting will be available in the app configuration and will contain the unique key that identifies you when using the 3scale service. This can be confirmed using the heroku config:get command.

$ heroku config:get THREESCALE_PROVIDER_KEY

After installing 3scale the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export THREESCALE_PROVIDER_KEY=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the THREESCALE_PROVIDER_KEY values retrieved from heroku config to .env.

$ heroku config -s | grep THREESCALE_PROVIDER_KEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Deployment overview

The integration of your API with 3scale is carried out using a plugin which can be used at any of the API endpoints you would like to cover with management services. These plugins are software libraries that are added to API application code to enforce traffic policies at the point of traffic entry.

Traffic to the API still comes directly and does not need to be redirected through third party machines. The plugins act as policy managers which track API keys and other credentials as well as assigned usage rights in order to both control who has access to your API endpoints and track how much traffic is being generated.

Each plugin implements:

  • Authentication calls to check only issued and non-suspended keys can access the API.
  • Verification that rate limits are not exceeded.
  • Traffic reporting to provide usage information into the 3scale analytics and rate limit components.

Below there are instructions for the Ruby, Node.js and Java plugins. You can find information for the rest of the plugins in their Github repositories and in the 3scale support portal.

Using with Ruby


Ruby applications will need to add the following entry into their Gemfile specifying the 3scale client library.

gem '3scale_client'

Then update application dependencies with bundler.

$ bundle install

If you are using Rails' config.gems, you can put this instead into your config/environment.rb.

config.gem '3scale_client'


First, create an instance of the client. Here is where you have to use the environment variable that was set when you provisioned the add-on.

client = ThreeScale::Client.new(:provider_key => ENV['THREESCALE_PROVIDER_KEY'])

You are now ready to authorize incoming API calls using 3scale. You just need to use the client object to make requests to the 3scale API.

This plugin supports the 3 main calls to the 3scale backend:

  • authrep grants access to your API and reports the traffic on it in one call.
  • authorize grants access to your API.
  • report reports traffic on your API.

3scale supports 3 authentication modes: App Id, User Key and OAuth. The first two are similar on their calls to the backend, they support authrep. OAuth differs in its usage two calls are required: first authorize then report.

Here is an example of how to use the plugin using the authrep call in App Id authentication mode.

response = client.authrep(:app_id => "the app id", :app_key => "the app key")
if response.success?
  # All fine, the usage will be reported automatically. Proceeed.
  # Something's wrong with this application.

You can check the complete reference for the Ruby plugin in its Github repository

Using with Node.js


The 3scale Node.js library is available at npm so installing it to your project is as easy as running:

npm install 3scale


To start authorizing API requests you need only create a a client object with your provider key. You should then use the methods available on that client object to authorize requests.

Notice how the provider key is obtained from the environment variable that was created when you added the 3scale add-on.

var Client = require('3scale').Client;
var providerKey = process.env.THREESCALE_PROVIDER_KEY;

client = new Client(providerKey);

client.authorize({app_id: "your application id", app_key: "your application key"}, function(response){

// Or for reports

var trans = [
              { "app_id": "your application id", "usage": {"hits": 1}},
              { "app_id": "your application id", "usage": {"hits": 1000}}

client.report(trans, function(response){

There are two alternatives for a successful integration with 3scale:

  • use the combination of one of the authorize methods and report
  • use one of the authrep methods, that performs the authorize and report operations atomically

To learn more about the details of the different available operations head over to the Service Management API documentation.

You can check the complete reference for the Node.js plugin in its Github repository.

Using with Java


The Java plugin is a Maven project, download and install it in the typical way.


This plugin supports the 3 main calls to the 3scale backend:

  • authrep grants access to your API and reports the traffic on it in one call.
  • authorize grants access to your API.
  • report reports traffic on your API.

3scale supports 3 authentication modes: App Id, User Key and OAuth. The first two are similar on their calls to the backend, they support authrep. OAuth differs in its usage two calls are required: first authorize then report.

Here is an example of how to use the plugin using the authrep call in API key authentication mode.

// import the 3scale library into your code
import threescale.v3.api.*;
import threescale.v3.api.impl.*;

//  ... somewhere inside your code

// get the provider key from the environment variable
String providerKey = System.getenv('THREESCALE_PROVIDER_KEY');

// Create the API object using the providerKey
ServiceApi serviceApi = new ServiceApiDriver(providerKey);

ParameterMap params = new ParameterMap();              // the parameters of your call
params.add("user_key", "your_user_key");               // Add the user key of your application for authorization
params.add("service_id", "your_user_key_service_id");  // Add the service id of your application

ParameterMap usage = new ParameterMap(); // Add a metric to the call
usage.add("hits", "1");
params.add("usage", usage);              // metrics belong inside the usage parameter

AuthorizeResponse response = null;
// the 'preferred way' of calling the backend: authrep
try {
  response = serviceApi.authrep(params);
  System.out.println("AuthRep on User Key Success: " + response.success());
  if (response.success() == true) {
    // your api access got authorized and the  traffic added to 3scale backend
    System.out.println("Plan: " + response.getPlan());
  } else {
    // your api access did not authorized, check why
    System.out.println("Error: " + response.getErrorCode());
    System.out.println("Reason: " + response.getReason());
} catch (ServerError serverError) {

You can check the complete reference for the Java plugin in its Github repository.

Alternative deployment using Nginx

Instead of using one of the software plugins, another way to integrate with 3scale is using an API proxy. This is an Nginx-based proxy that you deploy in front of your API server to play the role of an access control layer.

If you opt for this deployment method, the Heroku application for which you provision the add-on will be the one that holds the Nginx proxy and NOT your API server.

To deploy Nginx at Heroku you will need to follow the steps described in this tutorial.

While following that tutorial, you will have to provision the 3scale add-on right after the step where you create the Heroku application. This means that after you run:

$ heroku create --buildpack http://github.com/leafo/heroku-buildpack-lua.git

You will need to run the command to provision the add-on:

$ heroku addons:create threescale
-----> Adding threescale to sharp-mountain-4005... done, v18 (free)


For more information on the features available within the 3scale dashboard please see the docs at support.3scale.net.

The 3scale dashboard allows you to:

  • manage developer accounts and application credentials
  • set up plans with different sets rate limits for each of your endpoints
  • use the built-in CMS to create a custom developer portal for your API

The dashboard can be accessed via the CLI:

$ heroku addons:open threescale
Opening threescale for sharp-mountain-4005…

or by visiting the Heroku apps web interface and selecting the application in question. Select 3scale from the Add-ons menu.

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade threescale:newplan
-----> Upgrading threescale:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: threescale:newplan

Removing the add-on

3scale can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy threescale
-----> Removing threescale from sharp-mountain-4005... done, v20 (free)


You will find plenty of information and detailed tutorials in the 3scale support portal.

All 3scale support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at support@3scale.net.