Authentication

Calling the API

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

http://api.mashery.com/v2/rest/[site_id]

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:

http://api.mashery.com/v2/rest/[site_id]/reports/calls/median_volume_by_hour/service/[service_key]?apikey=2fvmer3qbk7f3jnqneg58bu2&sig=65a08176826fa4621116997e1dd775fa&start_date=2011-12-01T00:00:00Z&end_date=2011-12-08T00:00:00Z&format=json

Permissions

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.