HTTP Basic authentication

General method

You make a request over HTTPS with an Authorization header. The value of the header is the base64 encode concatenation of apikey:apisecret prepended with Basic

HTTPS is required for this method! Never perform basic authentication over an unsecured channel (HTTP) as your account credentials may be intercepted by a malicious third party.

Example

Our API key is foo, our secret is bar.

  1. The concatenation gives us the following

    foo:bar
  2. Base64 encoded this becomes

    Zm9vOmJhcg==
  3. So our final header looks like

    Authorization: Basic Zm9vOmJhcg==

Debugging basic authentication

You have followed the above steps but you're not getting the desired response?

BasicAuthenticationOverUnsecuredChannel

You have attempted to perform basic authentication over an unsecured channel. You can only use basic authentication over HTTPS.

Signature based authentication

General method

You make a request with three additional query parameters: apikey, time and signature:

Example

Our api key is foo, our secret is bar and we would like to make the following request:

http://api.farmaframe.be/v1/image/list?cnk=2&cnk=1
  1. We add the time parameter

    http://api.farmaframe.be/v1/image/list?cnk=2&cnk=1&time=2014-09-13T15:20:40.000Z
  2. We calculate the signature.

    1. We list the concatenation of all request parameters and their values and sort this list alphabetically (lexicographical byte value order).

      • cnk1
      • cnk2
      • time2014-09-13T15:20:40.000Z
    2. These values are then concatenated. The resulting string is called the base string

      cnk1cnk2time2014-09-13T15:20:40.000Z
    3. This base string should be prefixed with our api secret

      barcnk1cnk2time2014-09-13T15:20:40.000Z
    4. The MD hash of this string will be our signature

      0d72654fdccfd0ad79373f70ded76eb0
  3. we add our api key and the signature to our request:

    http://api.farmaframe.be/v1/image/list?cnk=2&cnk=1&time=2014-09-13T15:20:40.000Z&apikey=foo&signature=0d72654fdccfd0ad79373f70ded76eb0

    This is now a valid request that will pass signature authentication

Debugging signature authentication

You have followed the above steps but you're not getting the desired response?

MalformedIsoDate

The time parameter is not in ISO 8601 format

RequestTimeTooSkewed

The value in your time parameter differs too much from the time of the server. Have you specified your timezone?

InvalidApiKey

The specified api key does not exist

AccountDisabled

Your account has been temporarily disabled because of abuse.

AccountExpired

Your account is no longer valid. contact us to renew your subscription.

SignatureDoesNotMatch

The signature you calculated is wrong. The X-Expected-Basestring header will inform you of the base string we expected for this request.

UnsafeHttpMethodOverUnsecuredChannel

You are attempting to perform an operation that modifies data (http POST, PUT, or DELETE method) over an unsecure channel. You can only do these operations over HTTPS.

SensitiveInformationOverUnsecuredChannel

You are attempting to retrieve sensitive information over an unsecure channel. You can only do these operations over HTTPS.

Client side authentication

General method

You use our client side javascript library to access the api. With this library you can only access a subset of the features of our api, but you no longer have to worry about a lot of the little details.

Example

Using client side authentication outside of the client side javascript library is not supported.

Debugging client side authentication

Using the client side library but still not getting the desired response?

InvalidApiKey

The specified application key does not exist.

AccountDisabled

Your account has been temporarily disabled because of abuse.

AccountExpired

Your account is no longer valid. contact us to renew your subscription.

LocationDoesNotMatch

The domain your requests are coming from is invalid. Did you register your domains for use with the client library? The X-Expected-Location header will inform you of the domains registered for your api key and client key.

UnsafeHttpMethodOverUnsecuredChannel

You are attempting to perform an operation that modifies data (http POST, PUT, or DELETE method) over an unsecure channel. You can only do these operations over HTTPS. This error should not happen when using the client side library.

SensitiveInformationOverUnsecuredChannel

You are attempting to retrieve sensitive information over an unsecure channel. You can only do these operations over HTTPS. This error should not happen when using the client side library.

PartialAuthenticationNotSupported

The requested endpoint does not support client side authentication. This error should not happen when using the client side library.