API: Authentication

External application can access the 88 Miles API using OAuth 2.0. OAuth is a token based authentication system, which means your users can access their 88 Miles data without having to give you their username or password. Many popular languages already support OAuth 20, which should ease integration with you application. You can see if your favourite language is supported on the OAuth website.

Using an existing library will speed up your development, so it is recommended you have a look at one first. If you are interested in how the protocol works, or need more information to debug the require process, read on…

Getting Started

The first step to register you application. Go to the application page and fill in the details.

After you have registered your application, you will receive a client_id, client_secret. You can use these to authorize the user, and to get an access token which is your key to the user's account.

Authorization Grants

88 Miles supports three grant strategies: Authorization code, Implicit and Resource Owner Password Credentials.

Authorization code

The Authorization code strategy should be used if you can keep the client secret private. This will be the case if you are accessing the API via a web server, which will be able to store your client id and secret securely. You must first request a verification token, whch can be exchanged for an access token.

The Verification Token

To give your application access to a user's 88 Miles account, they will first need to verifier who they are. To do this, redirect the user to the authorize URL, with the following parameters:

An example URL might look like this:

https://88miles.net/oauth/authorize?client_id=NjtVKz6Di3ccJjn2AGwZKhSxYBX4QHPJ5w1LrZOR&client_secret=UxJrMUp9mV5AHaqXx62WuKToWk0nXxDYOgKDpQ8v&redirect_uri=http://mysite.com/callback

You user will be asked to login and click an authorize button. After they have done this, they will be redirected back to your callback URL. The URL will have a code and state parameter.

http://mysite.com/callback?code=aFfa5ssF&state=

Swapping the verification token for an access token

Now that the user has given you permission to access their data, you will need to swap the code you received for an access token. Make a POST to the token URL with the following parameters:

https://88miles.net/oauth/token?client_id=NjtVKz6Di3ccJjn2AGwZKhSxYBX4QHPJ5w1LrZOR&client_secret=UxJrMUp9mV5AHaqXx62WuKToWk0nXxDYOgKDpQ8v&redirect_uri=http://mysite.com/callback&code=aFfa5ssF&grant_type=authorization_code

This will return a JSON object with the access token

{ "access_token": "a8sDggsaa422Gglam", "token_type": "bearer" }

Implicit

If you are integrating 88 Miles inside a browser, or in a desktop or mobile app, where you can't guarentee the secret token can be kept secret, you may use the implicit grant type, which doesn't require the secret token. An access token will be returned straight away as a hash component when redirecting back to your callback_url.

You need to include the following parameters in your authorize URL:

Web apps can simply redirect to the token URL. For desktop and mobile apps, you will need to open an embedded browser instance — check your language's documentation on how to do this.

https://88miles.net/oauth/authorize?response_type=token&client_id=NjtVKz6Di3ccJjn2AGwZKhSxYBX4QHPJ5w1LrZOR&redirect_uri=http://mysite.com/callback

Once the user has authenticated and authorized, you can access the auth token directly from the hash component of the redirected URL

http://mysite.com/callback#access_token=SDWJFEenaVB7NJ09Vnm4KQTOBbXAiyMPmxpfcBYX&state=

Password

You may use the password grant, however, it is not recommended. It can be helpful when debugging or for accessing data from the command line, or if you can't easily provide a callback URL. Don't ever store a users login or password. That is why you are requesting an access token!

You will need to hit the token URL, rather than the authorize URL.

You need to supply the following parameters

https://88miles.net/oauth/token?grant_type=password&client_id=NjtVKz6Di3ccJjn2AGwZKhSxYBX4QHPJ5w1LrZOR&client_secret=UxJrMUp9mV5AHaqXx62WuKToWk0nXxDYOgKDpQ8v&redirect_uri=http://mysite.com/callback&username=login&password=password

The authentication token will be returned as a JSON string

{ "access_token": "a8sDggsaa422Gglam", "token_type": "bearer" }

Using the access token

To use the access token, simply set an Authorization header when you make an API request

Authorization: Bearer a8sDggsaa422Gglam

Notes

All API requests should be done over SSL.

Our access tokens don't expire - yet. We will be adding this shortly.

For more information of the OAuth 2.0 spec, Read the RFC.