Authorization and Authentication

What’s the difference?

For our purposes “authentication” refers to authenticating a user and “authorization” refers to proving you are legitimate application that has permission to access the API.

Application Authorization

There are certain GET methods that are allowed without any application identification.  This is allowed for some of our basic methods just to make it easier for people to integrate with it and get going.  These are things like pulling in the latest news or meets similar to what you might be able to pull with a typical RSS feed.

For any more complex methods, you will need to provide application authorization.   To get started, MileSplit needs to provide you with an API Key and a Secret Key.

• API Key – This is essentially your application’s user name.  In fact, we will set it as something that is simple, recognizable, and easy to remember.  There is no security concern with anyone else finding out this API Key.
• Secret Key – This is something that you should keep to yourself and buried in internal code.  You should never publish this or echo it to anything public visible, including Javascript source code!  It will be used to generate a hash on the server side and only that generated hash should ever appear in client code.

Application Credentials to Supply to API

You will pass two query parameters to the server for these purposes:

• k = The API Key
• h = The generated API Hash

Generating Your API Hash Key

The hash code is created by concatenating your API Key, Secret Key, and the IP address where the request will originate from.  Then you will MD5 that concatenation.  This hash protects security because it is not portable.  If someone intercepts it either from the source code or through a man-in-the-middle attack, it will be useless once they move it to another location.  Even if they know the procedure we use to generate the key, they will not be able to reproduce it without knowing your Secret Key.

The one thing that that might be a little tricky when generating this API key is that you have to think about what will be the requesting IP Address from the API’s perspective.  Generally, if it is PHP doing the request then you will use the server’s IP address.  If you are doing an AJAX request then you will use the IP Address of the end user’s machine.

User Authentication

Some methods, including all POST methods, also require a valid MileSplit user.  This will not only allow us to know who posted the content, but will allow us to enforce privacy and access permissions.

We will authenticate using a user authentication hash, which from here on we’ll refer to as the “user token” or just the “token”.

User Authentication to Supply to API

You will pass two query parameters to the server for these purposes:

• u = The user name of the account on MileSplit.
• t = The user token.

Generating the Token

The token is generated by an algorithm that is very similar to the formula we used to generate application authorization key.

To create this token, use the following steps:

1. Collect the user name and password (converted to all lowercase) and save the user name and immediately MD5 the password and save that.  User no circumstances should you save the actual password.  Any violation of this policy will result in your application being immediately suspended.
2. Concatenate the pre-hashed password, user name, your application secret key, and the IP address.
3. MD5 that concatenation.