• Register


Calling the API

All calls made to the Mashery V2.0 Reporting API share the following base:


where [site_id] is your designated Mashery site identifier.  To find out your site id, go to your Mashery Dashboard and look at the bottom of the page for the text "Mashery Site ID."

Mashery API key

The Mashery API requires a known token to be passed as part of the request query string. The token is called apikey. The value of the token is a 24 character alphanumeric string assigned by Mashery.

You can create a new Mashery API token by registering your application. Newly created keys must be approved by Mashery before they become active.  When you register we will be notified and will approve your key shortly.

You can review existing API keys under my account.

Signing the API Call

Each request must be signed. Valid signature is determined by examining a sig parameter from the query string of the request. The sig value is calculated by generating an MD5 hash made up of the API key, the API user's shared secret, and a UNIX timestamp reflecting number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) at the time the request was made. A five-minute wiggle is permitted on either side of the current timestamp on the Mashery server to allow for reasonable clock drift.

Most programming languages provide an md5()-type of function. The signature should be generated using such a function.

The following is an example of generating a valid signature with PHP:

$apikey = '2fvmer3qbk7f3jnqneg58bu2';  
$secret = 'qvxkmw57pec7';  
$timestamp = gmdate('U'); // 1200603038   
$sig = md5($apikey . $secret . $timestamp);  

An example request to the REST interface to the Mashery Reporting API, based on a timestamp of 1200603038 (Thu, 17 Jan 2008 20:50:38 +0000), an apikey of 2fvmer3qbk7f3jnqneg58bu2 and a secret of qvxkmw57pec7:



You must have permission in order to make a call into the Mashery Reporting API.  This permission is granted to the owner member of the API key.  This owner member must be created within your Mashery Developer Portal and it must be assigned an administration Role.  That role controls which API calls are allowed.

  • Administrator
  • Program Manager
  • Reports User

To grant API access to a user, grant the corresponding Mashery Dashboard Role.  For example, should you wish to have an apikey that has full access to all capabilities of the Mashery API, create or use a member within your site and grant them the "Administrator" Role.  Consult the documentation for each individual API call for the permissions required to make that call.

Authentication Errors

The following errors are indicative of permission, capacity, or authentication issues.

HTTP Status CodeError MessageDescription
403 Forbidden You have not been granted permission to access the requested method or object.
403 Not Authorized The API key associated with your request was not recognized or the signature was incorrect.
403 Account Inactive The API key you are using to access the Mashery API has not been approved or has been disabled.
403 Account Over Queries Per Second Limit The API key you are using has attempted to access the api too many times in one second.
403 Account Over Rate Limit The API key you are using has attempted to access the api too many times in the rate limiting period.
403 Rate Limit Exceeded The service you have requested is over-capacity.

Docs Navigation