Using REST

APIs on Mashape can be consumed with or without our client libraries: Here we guide you through the steps of consuming an API manually without using our clients, so that you'll be able to build your own client implementations.

Table of Contents

  1. APIs and REST
  2. Understanding API Authentication


APIs can be consumed by making regular HTTP requests. Remember to append the X-Mashape-Authorization header on every request valued with a Mashape Key. This header authenticates the user, and if it's missing the request won't go through.

To authenticate your client application with Mashape, it is required to provide a strong Mashape Test Key. There are two different kind of keys:

This key should be used only for strong testing purposes because it has unlimited access to every API.

Create a new restricted key every time you need to use an API in production. These keys can access only the APIs that you specify.

Keys should be kept secret and never shared with anyone!

Understanding API Authentication

API Profiles on Mashape describe the required parameters, and the expected response. Please read them carefully if you're having troubles consuming or parsing the response of an API.

Authenticating with OAuth

When an API is protected by OAuth 1.0a or OAuth 2.0 you need to take four additional steps before starting to consume the endpoints:

  • Properly configure the Callback URL property in the third party service settings.
  • Redirect the user to an auto-generated URL that we generate, and that will allow him to grant permissions to your app.
  • The user will be redirected back to your app where you can parse the OAuth Tokens.
  • Authorize the app against the API with the OAuth Tokens.

In the real-world if the API is protected by OAuth 1.0a, every request must submit a special OAuth signature. On Mashape, it’s easier to consume OAuth 1.0a because no signature is required on your side. Mashape automatically signs requests in the background.

Configure the Callback URL

Some services, like Twitter, GitHub or Facebook, require that you to specify a property called Callback in your Application settings.

  • The Callback URL is:

The real callback URL to your application is specified in the Mashape Client constructor instead.

Redirect the user

Before consuming the endpoints, your application must be granted permission from the user. You must redirect the user to an auto-generated URL (OAuth Redirect URL) that will start the authorization flow. After successful authentication, the user will be redirected back to a specified URL (the Custom Callback URL) where your application will be able to parse the required OAuth tokens to consume the API endpoints.

To get the OAuth Redirect URL you make an HTTP POST request to the /oauth_url endpoint of the API, with the following parameters:

curl -X POST -d "consumerKey=OAUTH-CONSUMER-KEY"
             -d "consumerSecret=OAUTH-CONSUMER-SECRET"
             -d "scope=OAUTH-SCOPE"
             -d "callback=CUSTOM-CALLBACK-URL"

You can get the OAuth credentials from the third party service. Most of them, like Twitter or GitHub, allow you to create Applications, and each application has its own pair of keys.

Parse the OAuth Tokens

If the user has granted permissions to your application, we'll redirect him back to the callback URL you specified while consuming /oauth_url, including two parameters:

  • accessToken
  • accessSecret - only if the API is OAuth 1.0a protected.

For example, if you specified the following Callback URL:

At the end of the OAuth flow the user will be redirected to:

You can store the OAuth credentials in your database and associate them with the user for every API request.

Authenticating and making requests

Before consuming the endpoint, you must authenticate the client with the parsed OAuth credentials.

Consuming with OAuth 1.0a

If you're consuming an OAuth 1.0a protected API, append the following headers to the request:

curl -H "X-Mashape-Authorization: YOUR-MASHAPE-KEY"
     -H "X-Mashape-OAuth-ConsumerKey: OAUTH_CONSUMER_KEY"
     -H "X-Mashape-OAuth-ConsumerSecret: OAUTH_CONSUMER_SECRET"
     -H "X-Mashape-OAuth-AccessToken: OAUTH_ACCESS_TOKEN"
     -H "X-Mashape-OAuth-AccessSecret: OAUTH_ACCESS_SECRET"

OAuth 2.0

If you're consuming an OAuth 2.0 protected API it's much more easier, just append the access_token parameter on every request:

curl -X POST -H "X-Mashape-Authorization: YOUR-MASHAPE-KEY" -d "access_token=ACCESS_TOKEN"

Support & Feedback

Please shoot us an email if you have questions or feedback or open a GitHub issue for bugs and feature requests: