Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
3scale integration plugin for Ruby/Ruby on Rails applications. 3scale is an API Infrastructure service which handles API Keys, Rate Limiting, Analytics, Billing Payments and Developer Management. Includes a configurable API dashboard and developer portal CMS. Support information at

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Client for 3scale web service management system API

This library provides client for the 3scale web service management API.


This library is distributed as a gem. First, add gemcutter to your gem source list, unless it's already there:

gem source --add

Then install the gem:

gem install 3scale_client

Or alternatively, download the source code from github:

If you are using Rails, put this into your config/environment.rb

config.gem "3scale_client"

Otherwise, require the gem in whatever way is natural to your framework of choice.


First, create an instance of the client, giving it your provider API key:

client = => "your provider key")

Because the object is stateless, you can create just one and store it globally.


To authorize a particular user, call the authorize method passing it the user key identifiing the user:

response = client.authorize(:user_key => "the user key")

Then call the success? method on the returned object to see if the authorization was successful.

if response.success?
  # All fine, proceeed.
  # Something's wrong with this user.

If both provider and user keys are valid, the response object contains additional information about the status of the user:

# Returns the name of the plan the user is signed up to.

If the plan has defined usage limits, the response contains details about the usage broken down by the metrics and usage limit periods.

# The usage_reports array contains one element per each usage limit defined on the plan.
usage_report = response.usage_reports[0]

# The metric
usage_report.metric # "hits"

# The period the limit applies to
usage_report.period        # :day
usage_report.period_start  # "Wed Apr 28 00:00:00 +0200 2010"
usage_report.period_end    # "Wed Apr 28 23:59:59 +0200 2010"

# The current value the user already consumed in the period
usage_report.current_value # 8032

# The maximal value allowed by the limit in the period
usage_report.max_value     # 10000

# If the limit is exceeded, this will be true, otherwise false:
usage_report.exceeded?     # false

If the authorization failed, the error_code returns system error code and error_message human readable error description:

response.error_code    # "usage_limits_exceeded"
response.error_message # "Usage limits are exceeded"


To report usage, use the report method. You can report multiple transaction at the same time:

response ={:user_key => "first user's key",  :usage => {'hits' => 1}},
                         {:user_key => "second user's key", :usage => {'hits' => 1}})

The :user_key and :usage parameters are required. Additionaly, you can specify a timestamp of transaction:

response ={:user_key => "user's key", :usage => {'hits' => 1},
                          :timestamp => Time.local(2010, 4, 28, 12, 36)})

The timestamp can be either a Time object (from ruby's standard library) or something that “quacks” like it (for example, the ActiveSupport::TimeWithZone from Rails) or a string. The string has to be in a format parseable by the Time.parse method. For example:

"2010-04-28 12:38:33 +0200"

If the timestamp is not in UTC, you have to specify a time offset. That's the “+0200” (two hours ahead of the Universal Coordinate Time) in the example abowe.

Then call the success? method on the returned response object to see if the report was successful.

if response.success?
  # All OK.
  # There was an error.

In case of error, the error_code returns system error code and error_message human readable error description:

response.error_code    # "provider_key_invalid"
response.error_message # "provider key \"foo\" is invalid"


Copyright © 2010 3scale networks S.L., released under the MIT license.

Something went wrong with that request. Please try again.