Overview of Healthx API and OAuth

OAuth is one standard mechanism for securing user data on the web. Healthx supports the OAuth standard for securing API requests to Healthx data. This page describes the Healthx implementation of OAuth and how to use it. For more information on the OAuth standard, see the OAuth.net documentation.

OAuth works by exchanging tokens for accessing data. There are two kinds of OAuth, 2-legged and 3-legged. Healthx supports both. You can read more about both kinds of OAuth at the excellent Beginner's Guide to OAuth.

OAuth - Two-Legged and Three-Legged

Two-Legged OAuth

Two-legged OAuth allows you to access data for an individual user, but without forcing the user to explicitly grant you access to this information. Instead, your application is granted access at registration. This access is deliberately restricted to specific API calls and data. All applications using two-legged OAuth must register here.

Three-Legged OAuth

Three-legged OAuth allows your application to access data on behalf of a user, with that users expressed permission granted through their Healthx username and password, entered into the Healthx site. Your application requests a request token, which is then authorized and exchanged for an access token. This access token, in turn, allows you to access the data explicitly defined by the user.

OAuth uses signed requests to pass data between applications. During the registration process you must choose the method your application will use to sign these requests. If you choose the RSA-SHA1 signature method, you'll be prompted to upload a certificate as a part of the registration process. If you choose HMAC-SHA1, you will eventually need to obtain a shared secret key. You can obtain this key at the end of the registration process, or later by managing your keys after you complete sign-up. Either way, you'll need this shared secret key for future OAuth transactions with Healthx. Read more about how you'll use these keys here.

As with any OAuth implementation, your application must be configured to securely save and manage OAuth tokens, and to handle the various scopes of access a user may choose. For example (in 3-legged OAuth), a user may choose to allow your application access to her user data, but not her eligibility data. It is your responsibility gracefully handle limited scopes.

When your application makes calls to the Healthx application, it does so by making a signed OAuth request[*]. This request is built using an Instance ID you obtain from a Healthx client organization. This allows the client organization the ability to opt in and opt out of your application's access rights at any time. One application might have several instance IDs representing one or more client organizations. We think this gives you maximum flexibility to write an application once and use it multiple times (with multiple instances).

OAuth Parameters

OAuth supports sending consumer request parameters as query string parameters, as parameters in the BODY of the request, or in the Authorization header of the request, in increasing order of preference. However, the Healthx implementation only accepts OAuth Protocol Parameters as part of the Authorization header. Other parameters (request parameters such as "MemberID") may be included in the query string or in the body of the request, as described in the documentation of the individual methods, but OAuth Protocol Parameters must be included in the Authorization header. We may offer extended support for sending these parameters in the BODY or query string in the future.

[*] The scheme and hosts of signed OAuth requests should be in lower case. See RFC5849.