API – User Management | 3scale API Management Solutions

3scale API for User Management

API version 1.1.1

The User management API for 3scale allows you to create, delete and manage users signed up for your service via a REST based API. This makes it possible to embed 3scale user management directly into your own existing customer facing applications or simply extract additional data for reporting purposes.

Specification

This document describes the protocol used for communication with 3scale backend server for user management.

Definitions

provider authentication key: Key that uniquely identifies the provider in the 3scale backend.
provider verification key: Key used by user to verify authenticity of the provider.
user key: Key that uniquely identifies the user.

Operations

These are all possible error identifiers and their meanings:

provider.invalid_key: Provider authentication key is not valid

This is example of error response:



<?xml version=“1.0” encoding=“utf-8” ?>

<error id=“user.invalid_key”>user_key is invalid</error>

TITLE

This operation is used to ….

POST /transactions.xml

Parameters

provider_key: (required) Provider authentication key
user_key: (required) user key

Configuration

Host:

server.3scale.net

Important Notice: For the API user creation to work you need to disable the option “Signup requires description of intended use?” under ADMIN / USAGE RULES on the control dashboard (login at http://www.3scale.net/admin. If this is not disabled you will get validation errors when creating users.

Methods

The methods available from the API are as follows.

User Signup

Request:

POST /plans/plan_id/signup.xml

The plan_id part has to be replaced with the id of the plan to signup the user to. Lists of available plans and their id’s can be obtained with the “Plan list” API call, described in the second part of this document.

Required parameters:

provider_key: (required) Provider authentication key
user[username]: (required) Unique username of the new user

Additional parameters (these are not required):

user[email]: User’s email address
user[first_name]: User’s first name
user[last_name]: User’s last name
user[password]: Password. If it is specified, the user will be activated and can log in into the system. (It is not recommended that this parameter be passed unless strictly necessary)
user_key: This sets a specific user key of your choice for the new account. In this case 3scale’s system will not generate a new random key for the account. The key must have alphanumeric characters on and be < 256 chars long. Further it must be unique (an exception will be raised if it is not). (Also see NOTE 1)

Response (success):

If signup was successful, the server responds with HTTP status code “201 Created”. The body of the response will contain XML formatted document looking like this:

  
  <contract>
    <user_key>3scale-36509454abf97aba7deacdef7c5661bd</user_key>
    <provider_verification_key>
     3scale-b2ac28b0e81b15dcdc839ccabe3c9276
    </provider_verification_key>
    <plan>
      <id type="integer">1234</id>
      <name>basic</name>
    </plan>
  </contract>

Elements

user_key: API key for the newly created user. You will need to pass this key with each API call to the 3scale backend, to identify the user.
provider_verification_key: This key can be used by user to verify the authenticity of the provider. If in use, this key should be send back to the user together with the API call response on each call to Your service.
plan: Element containing and sub-elements:
id ID of the user’s plan
name Name of the user’s plan

NB: usernames and email addresses are unique: if you try to create two users
one after the other with the same email address you should get the following back:

  
  <?xml version="1.0" encoding="UTF-8"?>
   <errors>
    <error>Email has already been taken</error>
   </errors>

Response (error):

If the provider_key parameter is invalid, the server responds with HTTP status code “403 Forbidden”.

If there is an error in the signup (for example: the username is missing, or is already taken) the server responds with HTTP status code “422 Unprocessable Entity”. The body of the response is XML formatted document looking like this:

  
  <?xml version="1.0" encoding="UTF-8"?>
  <errors>
    <error>Username is already taken</error>
  </errors>

That is, a root element , containing one or more elements whose content is the error description.

If a user with the user_key exists, an error results (422 Unprocessable Entity)

  
  <?xml version="1.0" encoding="UTF-8"?>
  <errors>
    <error>User key has already been taken</error>
  </errors>

Example request (NB – ensure this is a post):

  
  POST /plans/42/signup.xml HTTP/1.1
  Host: http://server.3scale.net
  Content-Type: application/x-www-form-urlencoded
  Content-Length: 76

  provider_key=3scale-49dd9c940f979a2e809056364d45cf65&user[username]=zoidberg

In order to set your own user key:

  
  POST /plans/42/signup.xml HTTP/1.1
  Host: http://server.3scale.net
  Content-Type: application/x-www-form-urlencoded
  Content-Length: 76

  provider_key=3scale-49dd9c940f979a2e809056364d45cf65&user[username]=zoidberg&user_key=mypfix-123456789

NOTE 1): When using your own keys via the user_key parameter is highly recommended that you set a custom key prefix for your account (ADMIN section, Usage Rules). The selected prefix should be included in the keys submitted via API.

Plan List

Request:

GET /plans.xml

Required parameters:

provider authentication key: Key that uniquely identifies the provider in the 3scale backend.

Response:

The server responds with HTTP status code “200 OK”. The body of the response contains XML formatted document looking like this:

 
  <plans type="array">
    <plan>
      <id type="integer">123</id>
      <name>free</name>
    </plan>
    <plan>
      <id type="integer">456</id>
      <name>basic</name>
    </plan>
  </plans>

That is, a root element , containing one or more elements, containing the plan id and plan name as and elements respectively.

Example request:

 
  GET /plans.xml?provider_key=3scale-49dd9c940f979a2e809056364d45cf65
  Host: http://server.3scale.net

Change Plans

Request:

POST to /buyer/plans/plan_id/change where “plan_id” is id of the new plan.

Required parameters:

provider authentication key: Key that uniquely identifies the provider in the 3scale backend.
provider verification key: Key used by user to verify authenticity of the provider.
username: Unique user name for the user whose plan you are changing.

Response on success:

Code “200 OK”, no body

Response on failure:

invalid provider_key:
Status code: “403 Forbidden”

Body
provider_key is invalid

invalid username:
Status code: “403 Forbidden”

Body
username is invalid

invalid plan_id:
Status code: “404 Not Found”
no body

View details of user’s contract

Request:

GET to /buyer/contract.xml

Required parameters:

provider authentication key: Key that uniquely identifies the provider in the 3scale backend.
username: The user’s username

Response on success:

“200 OK” with XML body looking like this:

 
  <contract>
    <user_key>3scale-36509454abf97aba7deacdef7c5661bd</user_key>
    <provider_verification_key>
       3scale-b2ac28b0e81b15dcdc839ccabe3c9276
    </provider_verification_key>
    <plan>
      <id type="integer">1234</id>
      <name>basic</name>
    </plan>
  </contract>

The response will also include status information on the user’s contract which lists the current usage of the users with respect to all metrics which currently have limits set for the user. This object takes the following form:

 
  <status>
   <usage metric="hits" period="month">
    <period_start>2009-08-01 00:00:00</period_start>
    <period_end>2009-08-31 23:59:59</period_end>
    <current_value>17344</current_value>
    <max_value>20000</max_value>
   </usage>

   <usage metric="hits" period="day">
    <period_start>2009-08-19 00:00:00</period_start>
    <period_end>2009-08-19 23:59:59</period_end>
    <current_value>732</current_value>
    <max_value>1000</max_value>
   </usage>

   <usage metric="hits" period="hour">
    <period_start>2009-08-19 22:00:00</period_start>
    <period_end>2009-08-19 22:59:59</period_end>
    <current_value>26</current_value>
    <max_value>100</max_value>
   </usage>
  </status>

Response on failure:

- the same as in “Change plan”

Example request:

 
  GET /buyer/contract.xml?provider_key=3scale-49dd9c940f979a2e809056364d45cf65&username=alice
  Host: http://server.3scale.net

Update user information

Host:

server.3scale.net

Request:

PUT /users/username.xml

The username has to be replaced with the username of the user to update.

Required parameters:

provider authentication key: Key that uniquely identifies the provider in the 3scale backend.

Additional parameters (these are not required):

user[email]: User’s email address
user[first_name]: User’s first name
user[last_name]: User’s last name
user[password]: Password. If it is specified, the user will be activated and can log in into the system. (It is not recommended that this parameter be passed unless strictly necessary)
user_key: If this field is NOT PRESENT no changes will be made to the user key. If the field is present by EMPTY then the 3scale system will REGENERATE a new uer key for this user. If the field is present and contains a value then the user key will be set to this value (see account creation for details).

Response (success)

If the update was successful, the server responds with HTTP status code “200 OK”. The response contains no body.

Response (error)

The same as for user signup.

Example request

 
  PUT /users/janette.xml HTTP/1.1
  Host: http://server.3scale.net
  Content-Type: application/x-www-form-urlencoded
  Content-Length: 112
  provider_key=3scale-49dd9c940f979a2e809056364d45cf65&user[email]=janette@example.com&user[password]=newpassword

Delete user

Host:

server.3scale.net

Request:

DELETE /users/username.xml

The username has to be replaced with the username of the user to be deleted.

Required parameters

provider authentication key: Key that uniquely identifies the provider in the 3scale backend.

Response

HTTP status code “200 OK”. No response body.

Response (error)

If the provider_key parameter is invalid, the server responds with HTTP status code “403 Forbidden”.

The system returns a 404 Page not found error (with no body) if the user does not exist.

Example request

 
  DELETE /users/janette.xml?provider_key=3scale-63be2d3b82f9f6e516f2414869052de9 HTTP/1.1
  Host: http://server.3scale.net

Annex I: Examples

Some brief examples using curl / wget. You can test the calls using the following calls:

the provider-key you can get from you “account” page when logged in and it will be something like:
3scale-5fc9d398ac038a4e8f212cc1e8cf01d2

If you have a code enabled on your site, you’ll need to append the argument (&…. – and put the URL in "" for curl) access_code= where the code can be found on the site page of your account settings.

Get the plans available

curl http://server.3scale.net/plans.xml?provider_key=

Sign a user up for a plan

curl -F user[username]= “http://server.3scale.net/plans/924795943/signup.xml?provider_key=”

Change plans

curl -F user[username]=“http://server.3scale.net/buyer/plans/924795944/change.xml?provider_key=”

Get information

curl “http://server.3scale.net/buyer/contract.xml?provider_key= &username=”

Annex II: PUT and DELETE HTTP methods

If your client does not support PUT or DELETE HTTP methods, they can be simulated using POST request with additional parameter “_method” with the value of “put” or “delete” respectively.

Example

Updating the user:

 
  POST /users/janette.xml HTTP/1.1
  Host: http://server.3scale.net
  Content-Type: application/x-www-form-urlencoded
  Content-Length: 124
  _method=put&provider_key=3scale-49dd9c940f979a2e809056364d45cf65&user[email]=janette@example.com&user[password]=newpassword

Deleting a user:

 
  POST /users/janette.xml?_method=delete&provider_key=3scale-63be2d3b82f9f6e516f2414869052de9 HTTP/1.1