App setup and authentication

To access the Nymbol API you need to provide authentication details via an HTTP header.

Obtaining an API key and secret

In order to obtain your authentication details:

  1. Go to https://nymbol.co.uk/apps.
  2. Click the Add a new app button.
  3. Enter the name of your app and provide a description.
  4. Choose the collection(s) you want the app to be able to access.
  5. Click the Add app button.

Once the app is saved, you'll see the API key for the app in the list. Click the app's name, then hover over the title to see both the key and the secret (you'll need both).

Note: You should use the same app details for all versions of the app (be they iPhone, iPad or Android apps, etc).

Authenticating with the API

Authentication details are passed to the API in the form of an MD5 hash.

Why MD5?

As of yet, Nymbol does not support storing user-identifiable data, or allowing users to explicitly identify themselves. For this reason, we thought that to begin with, MD5 would be the simplest way of allowing authentication that didn't send any identifiable information in plain text.

Unlike using standard HTTP authentication which sends a username and password in a readily decryptable form, we combine the details into a string which can't be decrypted. The Nymbol server receives this string, then compares it with an encrypted version of your API key and secret. If the two match, authentication passes.

If you have any concerns about the security of your data, please contact us.

Creating the hash and sending it in your HTTP request

You'll start off with a raw string, in the format <key>:<secret>. Run that through your MD5 library's hashing function to produce a hex digest (a 32-digit value).

To pass this to the API, set the Authorization HTTP header to the encrypted string.

Example

An authenticated request to the API might look something like this:

GET /api/manager/collection.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

When (and when not) to authenticate

In practice, you only need to authenticate when you're calling URLs that end in .json or .xml. All media (images, video, etc) is available without the need for authentication. This is intended to make a developer's life easier.

If authentication fails you'll receive an HTTP response with a 403 status code.

Further reading and resources

Next guide: Collections and assets →