Authentication

RunningAHEAD.com uses OAuth 2.0 for authentication. OAuth is a specification that allows users to grant your application access to their data without revealing their passwords. RunningAHEAD.com's OAuth implementation currently supports the web server and installed application scenarios.

This page documents the steps to authenticate with the RunningAHEAD API and to request access to a user's training data. In a nutshell, you register your application with RunningAHEAD.com, redirect the browser to a URL to obtain an authorization token which is then send back to RunningAHEAD in exchange for an access token for a given user.

Step 1: Register Application

To be filled in when implemented...

Step 2: Request Authorization Token

Before your application can gain access to the user's data, it must first request access from the user by redirecting the user's browser to the following endpoint in combination with the query parameters:

GET https://www.runningahead.com/oauth2/authorize

Parameters

Parameter	Values	Description
response_type	code (required)	Must be set to code.
client_id	the application key	The client_id identifies the application that's making the request. The key is given to you when you registered the application.
redirect_uri	One of the redirect_uri values registered during application registration	Determines where the response is sent. The value of this parameter must be URL encoded. It must exactly match one of the values registered during application registration. Web Server Scenario If your application is web server based, then the URL must be within your domain. Mobile Application Scenario If you are creating a mobile device app, you may set redirect_uri to either urn:ietf:wg:oauth:2.0:oob or an http://localhost port. The two URLs tells how to process the response. If your application specifies urn:ietf:wg:oauth:2.0:oob, then RunningAHEAD.com will not redirect the browser. Instead, it will set the title of the page to the authorization token. The confirmation page will also display the token to allow the user to manually enter the code in your application. To use urn:ietf:wg:oauth:2.0:oob, your application should host the web browser. It should monitor the web browser for the presence of the token. If your application has its own web server, then it can use the http://localhost as redirect_uri. The web server must process the redirected url to parse for the authorization token.
state	any string	An optional parameter used to identify the state of your application. The state parameter is treated as an opaque value and is not used by the server. It will be passed back to you in a parameter in the redirect_uri.

Example

  https://www.runningahead.com/oauth2/authorize?
  client_id=59fa8d0c61c14c5cb6b906ac29b8e7d7&
  redirect_uri=http%3A%2F%2Fwww.mywebsite.com%2Foauth_callback&
  response_type=code&
  state=%2Fprofile

In this example, and for the rest of this page, the redirect_uri will be http://www.mywebsite.com/oauth_callback. You will need to replace this value with a URL specific to your domain.

Web Server Scenario Response

After the user grants access to the data, the web server will generate an authorization token. The token is returned to your application by redirecting the browser to redirect_uri with the token as the code parameter. If your application includes the state parameter in the request URL, it will also be appended to redirect_uri.

http://www.mywebsite.com/oauth_callback?code=VjU5s4dyhAPO2XiUzaNVeE&state=%2Fprofile

Mobile Application Scenario

If http://localhost is the value of redirect_uri, then the response is the same as the web server scenario above.

If your application specifies urn:ietf:wg:oauth:2.0:oob, then RunningAHEAD.com will not redirect the browser after the token is generated. Instead, the token will be set as the title of the resulting page.

Authorization Token

The authorization token is set to expire 10 minutes after it is granted.

Error Response

If your request results in an error, the server will emit the following parameters. How they are formatted depends redirect_uri.

Parameter	Type	Description
error	string	These are the standard OAuth 2.0 error codes. One of the following: access_denied invalid_request invalid_scope server_error temporarily_unavailable unauthorized_client unsupported_response_type
error_description	string	A user readable error message, although the message is intended for you to debug the error.

If your application has specified redirect_uri, then the server will redirect the browser to the specified redirect_uri, with the error code and optionally error message as part of the query string. If the request contains the state parameter, it will be included in the url.

http://www.mywebsite.com/oauth_callback?
error=invalid_request&
error_description=missing+response_type&
state=%2Fprofile

If the redirect_uri is urn:ietf:wg:oauth:2.0:oob, then the error parameters will be the sole content of the request page's body.

error=invalid_request&error_description=missing+response_type&state=%2Fprofile

Step 3: Request Access Token

After you received the authorization token from RunningAHEAD.com, you will need to exchange the token for an access token, which will allow you to access the user's data. Submit the authorization token to the following endpoint using HTTP POST:

POST https://api.runningahead.com/oauth2/token

Parameters

Parameter	Values	Description
client_id	string (required)	The client's key issued to you during application registration.
client_secret	string (required)	The client's secret issued to you during application registration.
code	string (required)	The authorization token.
redirect_uri	string	The exact redirect_uri used in the authorization phase.
grant_type	string (required)	Must be set to authorization_code.

Example

POST /oauth2/token HTTP/1.1
Host: api.runningahead.com
Content-Type: application/x-www-form-urlencoded

client_id=59fa8d0c61c14c5cb6b906ac29b8e7d7&
client_secret=8973294376d14891a410de5fbb72df89&
code=VjU5s4dyhAPO2XiUzaNVeE&
grant_type=authorization_code&
redirect_uri=http%3A%2F%2Fwww.mywebsite.com%2Foauth_callback

Success Response

If the authorization token is valid, the endpoint will return an access token the form of a JSON object:

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

The access token currently does not have an expiration date. However, the user can optionally deny your application from future access by revoking the access token. The access token contains at most 32 characters.

You can now use the access token to access the user's training data using the API.

Error Response

If your request contains an error, the server will return the error code in the response:

{
    "error": "invalid_request",
    "error_description": "missing response_type"
}