Basic Auth

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).

Example

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
QWxhZGRpbjpvcGVuIHNlc2FtZQ==

2) Make the request

GET /v2 HTTP/1.1
Host: api.appfigures.com
X-Client-Key: your-client-key
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

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

Curl Example

# gets products using app key header
curl -H'X-Client-Key: MY_CLIENT_KEY' -u'USERNAME:PASSWORD' \
      'https://api.appfigures.com/v2/products/mine';

# gets products using app key qs parameter
curl -u'USERNAME:PASSWORD' \
      'https://api.appfigures.com/v2/products/mine?client_key=MY_CLIENT_KEY';

Authentication Errors

The API can return the following errors when authenticating requests

Bad Credentials

// HTTP 401 Authorization Required
{
  "status": 401,
  "message": "Could not authenticate: rob@fobsdirect.com",
  "additional": "",
  "reference": ""
}

No API Access – Locked Account

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

// HTTP 403 FORBIDDEN

{ 
    "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 https://appfigures.com/account/billing

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:

// HTTP 403 FORBIDDEN

{ 
    "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.