API

OAuth Documentation

API Authorization

OAuth 2.0 is an open protocol that allows a user to authorize a third-party application to access their data from a Web service. OAuth is used by Facebook, Google, Twitter, LinkedIn and many others either support or plan to support it.

Third-party applications built on dailymile must use OAuth to authenticate. This API supports OAuth 2.0, draft 11. We recommend using an OAuth library rather than building requests yourself. There are libraries already built for most languages, some of which you can find here.

OAuth 2.0 authentication works by asking the user to authorize your app. Once a dailymile user has authorized your application, your application can access that user's protected resources by using an oauth token.

We support various authentication flows depending on whether you're a Web app, using Javascript, or a native mobile app.

Client Profiles

Authenticating from a Web Server

Using OAuth 2.0, you'll get an access token for a dailymile user. Once you have this token, you can use it to access protected resources on behalf of the user who authorized it by passing it in each request. Access tokens are long-lived and won't expire unless the user explicitly revokes access to your app. Let's get started!

1. Register your application

To get started using OAuth, you'll first have to register your application. The callback URL that you enter is what we'll redirect users to after they authorize your application. Once you do that, you'll get your client ID which you'll use in the next step.

2. Ask user to authorize your application

To get an access token for a user, you'll need to ask them to authorize your application by redirecting them to dailymile. You'll need your client ID and the callback URL that you registered with in the previous step. From your app, redirect the user to https://api.dailymile.com/oauth/authorize?response_type=code with the parameters client_id set to you client ID, and redirect_uri set to the callback URL you provided when you registered your app.

  https://api.dailymile.com/oauth/authorize?
    response_type=code&
    client_id=<CLIENT_ID>&
    redirect_uri=http://www.example.com/callback

3. Get user's access token

If the user authorizes your application, we'll redirect to the URL you passed in the redirect_uri param in the previous step with a new parameter called code appended. You'll exchange this code parameter for an access token by POSTing to https://api.dailymile.com/oauth/token?grant_type=authorization_code. You'll pass the same client_id and redirect_uri params you used in the last step, but this time you'll also include the client secret you received when you registered your app as client_secret and code param in the URL that we redirected to.

  curl -d "grant_type=authorization_code& \
           client_id=<CLIENT_ID>& \
           client_secret=<CLIENT_SECRET>& \
           redirect_uri=http://www.example.com/callback& \
           code=<AUTHORIZATION_CODE>" \
          https://api.dailymile.com/oauth/token

If successful, we'll return a response that has a JSON body containing your access token:

  { 
    "access_token": "<ACCESS_TOKEN>"
  }

Authenticating from a User-Agent

The User-Agent flow is is typically executed within a browser using JavaScript. You'll receive the access token as part of the user authorizing your app (as opposed to making a separate request as you would in the Web Server flow). You won't use your client secret as part of this flow since it's accessible.

1. Register your application

To get started using OAuth, you'll first have to register your application. The callback URL that you enter is what we'll redirect users to after they authorize your application. Once you do that, you'll get your client ID which you'll use in the next step.

2. Ask user to authorize your application

To get an access token for a user, you'll need to ask them to authorize your application by redirecting them to dailymile. You'll need your client ID and the callback URL that you registered with in the previous step. From your app, redirect the user to https://api.dailymile.com/oauth/authorize?response_type=token with the parameters client_id set to you client ID, and redirect_uri set to the callback URL you provided when you registered your app.

  https://api.dailymile.com/oauth/authorize?
    response_type=token&
    client_id=<CLIENT_ID>&
    redirect_uri=http://www.example.com/callback

3. Extract access token from URL fragment

When the user authorizes your application, we'll redirect to the callback URL you passed as a param and you can extract the access token from the URI fragment:

  http://www.example.com/callback#access_token=<ACCESS_TOKEN>

Authenticating from a Native Application

Coming soon!

You're ready!

Now that you've got an access token for a user, you're ready to request any protected resources on behalf of the authorizing user that are listed in the API Documentation. Note that all OAuth protected resources must be accessed with HTTP over TLS. Simply pass the access token you received for the user in each request as the oauth_token param.

  curl 'https://api.dailymile.com/people/me.json?oauth_token=<ACCESS_TOKEN>'

Please let us know if you have any trouble.