Registration & Authorization

The API is designed to enable deep connections between your application and user's Health Graph information. Fitness activities, Health-focused measurements, and Heath Graph social information can all be written into and read from via the API. Follow the quick guide below to take the first steps to getting your integration authorized, running smoothly and published.

The Health Graph API uses OAuth 2.0 for security (revision 15 at the time of this writing). OAuth enables users to use your product with their Health Graph account (RunKeeper account) without having to share their passwords. Many popular platforms, such as Facebook and Twitter, use OAuth as their preferred protocol for controlling and protecting access to their users' information.

Register your Application

To start, register your application with the Health Graph in the Applications Portal. Be sure to provide the name of your application, an informative description, the name of your organization, and a link to your application's website during the registration process--users will be presented with this information when connecting your application to their accounts. Once registered, your application will be assigned a unique identifier and shared secret key for use with the Health Graph API.

After registration, you can being accessing the Health Graph immediately. All applications can read/write access to their users' profile settings and preferences, and are allowed to record new activities and health measurements ("basic access"). Additionally, an application can read and edit the activities and measurements of the user who registered it. If your application needs read and/or edit access to the health information of other connecting users, be sure to check "Read Health Information" (and "Edit Health Information", if appropriate) under "Special Permission Requests" on the registration form, and explain what your application will do with this data.

If your application may retain a user's information after disconnection from the Health Graph, be sure to check "Retain Health Permission" so that the user is properly informed. If the user chooses to disconnect your application, the system will present a dialog asking whether any shared information should be retained or deleted. The system will then include the user's choice in application requests for a disconnected account.

Connect your Application to a User's Health Graph Account

OAuth defines a number of "flows" for connecting accounts. Currently, the Health Graph supports the "Authorization Code" flow for third-party applications.

Endpoint URLs can be found on the "Keys and URLs" page in the Partner Portal for your application.

  1. Direct the user to the Health Graph API authorization endpoint. Be sure to include the following request parameters:
    • client_id: The unique identifier that your application received upon registration
    • response_type: The keyword 'code'
    • redirect_uri: The page on your site where the Health Graph API should redirect the user after accepting or denying the access request

    Optionally, you can also include a state parameter with a URL-safe value that has meaning specific to your application. The authorization endpoint will return this value when responding to your application in step 2 below.

  2. The Health Graph API will prompt the user to log in (or create an account if needed), state that your application would like access to his/her account, and ask whether to allow the request:

    The login screen
    The authorization screen

    If the user permits, the Health Graph API will redirect him/her to the redirect_uri that you supplied above with the following parameters:

    • code: A one-time authorization code that you will need to obtain an access token
    • state: The value of the state parameter supplied in step 1 (omitted if your application did not supply a state parameter)
  3. Make a POST request to the Health Graph API token endpoint. Include the following parameters in application/x-www-form-urlencoded format:
    • grant_type: The keyword 'authorization_code'
    • code: The authorization code returned in step 2
    • client_id: The unique identifier that your application received upon registration
    • client_secret: The secret that your application received upon registration
    • redirect_uri: The exact URL that you supplied when sending the user to the authorization endpoint above

The Health Graph API will respond, in application/json format, with the parameter 'access_token' set to a string that uniquely identifies the association of your application to the user's Health Graph/RunKeeper account. Include this string as an HTTP "bearer token" or as the 'access_token' parameter in any request that you make to the Health Graph API.

If the user refuses access to his/her account, the Health Graph API will respond to the initial authorization request by redirecting the user to the redirect_uri with the parameter 'error' set to 'access_denied.' (This response will also include the supplied state parameter, if any.)

Disconnecting from the Health Graph

There are two ways to disconnect an application from the Health Graph:

  1. The user can disconnect your application via the Settings page for his/her account; or,
  2. Your application can make a POST request to the de-authorization endpoint. Include the following parameters (in application/x-www-form-urlencoded format):
    • access_token: The access token for the connection to remove
    If the request is successful, the server will return an HTTP status code of 204 (No Content).

When registering your application, you can specify an authorization removal callback URL. The Health Graph will notify you whenever a user disconnects your application from his/her account by making a POST request to this URL (in application/json format) with the following fields:

  • access_token: The revoked access token
  • delete_health: A Boolean value indicating whether the user has requested that your application delete any cached activities and health measurements that originated from the Health Graph

Additionally, a request to the Health Graph API that uses a revoked access token will result in a 403 response, which will contain a machine-readable message indicating that the user has disconnected your application and whether the user would like to delete any cached information.