Calling the API
All calls made to the Mashery V2.0 Reporting API share the following base:
[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
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.
- 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.
The following errors are indicative of permission, capacity, or authentication issues.
|HTTP Status Code||Error Message||Description|
|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.
- Support Documentation Portal
- IO Docs Definition
- Mashery API Documentation
- Mashery 3.0 API Guide
- Resource Hierarchy
- Pagination, Sorting, Filtering
- Example Use Cases
- Email Template Sets
- Mashery 2.0 API Guide
- OAuth Supporting Methods
- API Sandbox
- JSON RPC
- API Objects
- Fetching Objects
- Query Language
- Creating Objects
- Updating Objects
- Validating Fields
- Deleting Objects
- General Object Methods
- Plan Services
- Plan Endpoints
- Plan Methods
- Plan Filters
- Package Keys
- Developer Classes
- Defining Methods
- Service Definitions
- Service Definition Endpoints
- Service Definition Methods
- Service Definition Response
- Mashery 2.0 Reporting API Guide
- Event Trigger API
- Mashery 1.0 API Guide
- Mashery 3.0 API Guide
- Tips and Tricks
- Customizing Your Portal
- API Traffic Manager
- I/O Docs WSDL requirements