Whichever authentication scheme you use, you’ll need to go to to get a client_key and client_secret for your app.

We suggest that any client that is capable of using OAuth 1.0 uses it. We require that any client made publicly available use OAuth 1.0. This is to protect the safety of our user’s credentials.
If you are creating a client that can’t use OAuth 1.0 and is for internal/team use only then feel free to use HTTP Auth.

Requests made with HTTP Auth still require a client_key to be given. Requests without a client_key or those where where the client_key’s owner differs from the account that’s authenticated will be rejected with a 403.

So if you create a client_key you can use HTTP Auth to explore the API in your browser or easily process data with command line utilities. However, even if you have or have been given access to someone else’s credentials
you’ll be unable to authenticate without having a client_key that was also created by their account.

Both schemes are outlined in detail below.

OAuth 1.0

If you already have experience with OAuth, here’s what you should need to get running with our API.

  • Consumer Registration URL:
  • Request Token URL:
  • User Authorization URL:
  • Access Token URL:
  • Signature Methods: HMAC-SHA1 or PLAINTEXT

Note: Our handling of scopes does not conform to the spec (because there’s no spec for scopes). Have no fear if you are using an existing client: scopes in the client are optional, if they aren’t specified the access tokens will inherit the scope given when the client key was created.

There are quite a few preexisting OAuth clients out there in the world. The OAuth group maintains a comprehensive (but not necessarily complete) list of clients. If you don’t want to use a prebuilt client and you’d like to implement OAuth manually, check out our walkthrough.

HTTP Authentication

HTTP Authentication is built into most HTTP language’s standard libraries and clients, so you won’t actually have much to do to get started.
If you are only making requests to get data from accounts you directly control you can use this scheme.

Important: If you want to allow other people to authenticate in your app this will not work! To access account data that is not from the same account as the one that issued your app key you must use OAuth.

The API supports Basic Auth mode and you’ll need to send along your client_key (that you got when you create an API client.

The preferred way to do this is in the X-Client-Key header. If you’re using a platform or client that doesn’t make it easy to add custom headers you can also send it in the client_key=KEY query string parameter.

If you need to implement HTTP Basic Auth yourself it’s pretty simple. Just add an Authorization header to your request with the username and password separated by a colon and base64 encoded, preceded by the word “Basic” and separated by a space.

Or put otherwise the full header line would be in this form: Authorization: Basic CREDENTIALS, where CREDENTIALS is base64(USERNAME + ":" + PASSWORD).


That’s quite a mouthful, here’s an example.

This is what a request might look like for the user ‘Aladdin’ and password ‘open sesame’:

1) Generate the correct credentials string

$ echo -n 'Aladdin:open sesame' | base64

2) Make the request

GET /v2 HTTP/1.1
X-Client-Key: your-client-key
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Where QWxhZGRpbjpvcGVuIHNlc2FtZQ== is base64(“Aladdin:open sesame”)

Curl Example

# gets products using app key header

# gets products using app key qs parameter

Authentication Errors

The API can return the following errors when authenticating requests

Bad Credentials

// HTTP 401 Authorization Required
  "status": 401,
  "message": "Could not authenticate:",
  "additional": "",
  "reference": ""

No API Access – Locked Account

The API will return the following when an account is suspended because of a billing issue:


    "status": 403, 
    "message": "No API Access", 
    "additional": "The authenticated account is locked due to an unpaid balance." 

In this case you may want to offer a direct link for the user to make a payment

API Access is disabled

The API will return the following for a user that has been suspended due to a violation of the API terms:


    "status": 403, 
    "message": "API Access is disabled", 
    "additional": "API access has been disabled for this user due to API terms violation." 

No App Key given

// HTTP 400 Bad Request

  "status": 400,
  "message": "Must give an app key via X-Client-Key header or client_key query string parameter",
  "additional": "",
  "reference": ""

To resolve a violation of terms issue contact us.