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 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).
[*] The scheme and hosts of signed OAuth requests should be in lower case. See RFC5849.
Developer Services >