Authentication

In the past the API used to use only HTTP Authentication for clients. This was good because it was relatively secure when used over HTTPS and supported by nearly anything that would want to talk to it (excel, anyone?). The big issue with HTTP Auth is when you are using an API client that you yourself didn’t create you need to trust it with your credentials.

Sometimes that can be scary, so V2 of the API supports both HTTP Auth(Basic)* and OAuth 1.0a. OAuth is significantly more complicated than HTTP Auth, but requires no passwords to be given and gives granular ability to revoke access. On the bright side, there is an OAuth library for nearly any language or stack under the sun. If you just want to see it done, check out our code samples

Basics

Whichever authentication scheme you use, you’ll need to go to https://appfigures.com/developers/keys 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
https://appfigures.com/developers/keys

Request Token URL
https://api.appfigures.com/v2/oauth/request_token

User Authorization URL
https://api.appfigures.com/v2/oauth/authorize

Access Token URL
https://api.appfigures.com/v2/oauth/access_token

Signature Methods
HMAC-SHA1 or PLAINTEXT

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.

Remember, 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 both Digest and Basic modes and in both cases you’ll need to send along the client_key that you got earlier at https://appfigures.com/developers/keys’. 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 Examples

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

  • Seva Alekseyev

    HTTP Basic auth is broken.

    Whenever I provide my e-mail and password, base64-encoded, the back-end reponds “Could not authenticate: “. If the username contains no @ character, it says: “Could not authenticate: username”

    But I have no @-less username, only e-mail address.

    • appfigures

      We’re not seeing any issues with the API. Have you tried encoding the @?

      • Seva Alekseyev

        Encoding how? As in a URL? Tried that, it says “Could not authenticate: sevaa%40sprynet.com”. Looks like it doesn’t decode.

  • Sean White

    :%s/X-Client-Key/X-App-Key/g 🙂

    • alexquick

      Good catch. We’re in the process of integrating OAuth and documenting it. I’ll make sure the current codebase is made forwards compatible so the new documented key header and qs parameters are correct.