NAV

Introduction

Welcome to the HealtheIntent open development documentation. The HealtheIntent open development ecosystem allows access to population health based concepts through RESTful APIs. These APIs are meant to be consumed by other systems/applications in a B2B (Business to business) context. As such, there is no user-level authorization or filtering applied; it is expected that the systems/applications interacting with these APIs are applying the appropriate authorization controls for end users.

Authentication

The HealtheIntent APIs use two-legged OAuth 1.0a based authentication. In order to make calls to the APIs you will need a Cerner system account which can be used as a set of OAuth credentials called consumer key and consumer secret. The HealtheIntent APIs use the two-legged (or B2B) OAuth 1.0a flow. For detailed documentation see the OAuth 1.0a spec.

Requesting OAuth 1.0a Credentials

A system account can be requested through the CernerCentral administrative portal. For development accounts, please prefix the account name with ‘HealtheIntent Dev Partner - ’. Once the account is approved, please send the account ID to your HealtheIntent development partner to have the account granted access to the development environment.

Making OAuth Calls

Since the APIs are protected using the two-legged OAuth 1.0a flow rather than the more common three-legged flow, it is recommended to test making an OAuth call using a browser or curl prior to writing any code. This helps you get familiar with the fundamentals of the two-legged flow before using any third party libraries. Many third party libraries are optimized for the three-legged flow and may be difficult to use with the two-legged flow.

Prerequisites

Retrieving an access token

Curl can be used to test retrieving an access token. The following examples will use 32dc21c-8ece-4ada-89b3-c152713f0575 as an example consumer key and L5ZeC0mVyot2C-KQlkXg5egglZsIphaC as an example consumer secret. You would replace these values with your own consumer key and secret.

Example request (multiline for readability):

curl -X POST -d "oauth_consumer_key=32dc21c-8ece-4ada-89b3-c152713f0575\
&oauth_signature_method=PLAINTEXT\
&oauth_signature=L5ZeC0mVyot2C-KQlkXg5egglZsIphaC%26"\
 https://api.cernercare.com/oauth/access

Example response:

oauth_token=ConsumerKey%3D332dc21c-8ece-4ada-89b3-c152713f0575%26ExpiresOn%3D1461779242%26HMACSecrets%3DL-RNB8AAMQM6iIdiP9m091f-JwYpcsJKj18SJNaGVqBtx7t0NA1SLVxm0cKvatdK4o3cb5sHPpHsr8rcNSofmzbX39sS2MsQc81cdjr0_HyBlKgC2rIy_2TRzjGvytsv0B5daJUmuA-EPW6U0-o7BQ%253D%253D%26KeysVersion%3Dfcecee6b-0c23-4df5-a332-799f9a515c16%26RSASHA1%3DOg5rz-58zVBJ924PSgOGoT34vOBOBNsbYNn_i1HijNDhbb_H3PbQXIFKvAcSU636hdqVT2eDeoRgz7aDitlmkvpFZuK3yi-cEYSFXIXuRmagHWeVYQs8A8I3WdZ-yritAwwfTESOGqXmomP6hC-2wiR_WFzqbGJcFcGVqdv2VqzMPgtd3CGz7KoTlOKSacBPq0AHGcu_PCm3oIlrgNReUZdm89MG7MkWNeGFOxiwMHKUzr4oZqwRehZb6LdpYrBJ0vYu94Qg-V_0UME9b7RIASXLtcTtducEREpDCwQZ0MqMsL0mXQ20dDfDD7t7AUziJZELZIDjTB4tPNZD3-aukQ%253D%253D&oauth_token_secret=Qsk0auN5DOu3C9IbkHq2jE5Q6hMI3Nd_&oauth_session_handle=mEYrqIb_zM8sNpReS8AFwvSNOef5Tz2K&oauth_expires_in=3600&oauth_authorization_expires_in=86400

Using the access token to call a protected API

Given an access token it is now possible to call a protected API.

The following information will be needed from the access token response:

The Authorization header is used for calling protected APIs. The header can be built using the structure below. The built header should then be added when calling Protected APIs.

The oauth_signature is built by appending the oauth token secret from the access token response to your consumer secret, separated by a URL encoded ampersand like so: oauth_signature=<your-consumer-secret>%26<oauth-token-secret>`

Example authorization header (multiline for readability):

OAuth oauth_token="ConsumerKey%3D332dc21c-8ece-4ada-89b3-c152713f0575%26ExpiresOn%3D1461779242%26HMACSecrets%3DL-RNB8AAMQM6iIdiP9m091f-JwYpcsJKj18SJNaGVqBtx7t0NA1SLVxm0cKvatdK4o3cb5sHPpHsr8rcNSofmzbX39sS2MsQc81cdjr0_HyBlKgC2rIy_2TRzjGvytsv0B5daJUmuA-EPW6U0-o7BQ%253D%253D%26KeysVersion%3Dfcecee6b-0c23-4df5-a332-799f9a515c16%26RSASHA1%3DOg5rz-58zVBJ924PSgOGoT34vOBOBNsbYNn_i1HijNDhbb_H3PbQXIFKvAcSU636hdqVT2eDeoRgz7aDitlmkvpFZuK3yi-cEYSFXIXuRmagHWeVYQs8A8I3WdZ-yritAwwfTESOGqXmomP6hC-2wiR_WFzqbGJcFcGVqdv2VqzMPgtd3CGz7KoTlOKSacBPq0AHGcu_PCm3oIlrgNReUZdm89MG7MkWNeGFOxiwMHKUzr4oZqwRehZb6LdpYrBJ0vYu94Qg-V_0UME9b7RIASXLtcTtducEREpDCwQZ0MqMsL0mXQ20dDfDD7t7AUziJZELZIDjTB4tPNZD3-aukQ%253D%253D",
oauth_consumer_key="332dc21c-8ece-4ada-89b3-c152713f0575",
oauth_signature_method="PLAINTEXT",
oauth_signature="L5ZeC0mVyot2C-KQlkXg5egglZsIphaC%26Qsk0auN5DOu3C9IbkHq2jE5Q6hMI3Nd_"

Base URIs

HealtheIntent is a multi-tenant platform. All APIs are documented as HTTP paths relative to a tenant-specific hostname. HealtheIntent hostnames are provisioned using the following pattern:

  https://{client}.{solution}.healtheintent.com
  {client} => The tenant identifier.
  {solution} => The solution identifier

Examples for cernerdemo tenant:

HTTP Status Codes

Cerner uses standard HTTP status codes standard HTTP status codes to indicate the success or failure of an API request. Generally, codes in the 2xx range indicate success, codes in the 4xx range indicate a problem with your request, and codes in the 5xx range indicate a problem on our end. The HealtheIntent APIs use the status codes below. More details about the possible responses for each endpoint are listed in the Responses sections on the pages for the APIs.

Code HTTP Definition Meaning
200 Success Everything worked as expected.
201 Created Your item was created.
204 No content Returned for PUT, POST, or DELETE requests when you should not expect a response body to be returned.
304 Not modified Returned for conditional 'GET’ requests when nothing has changed since the previous request.
400 Bad request Your request could not be understood by the server, often due to bad syntax or parameters.
401 Unauthorized Your request did not have valid authentication credentials.
403 Forbidden Your request had valid authentication credentials, but those credentials are not allowed to complete the requested operation.
404 Not found The resource you requested doesn’t exist.
409 Conflict Your request failed due to a conflict with the current state of the resource.
412 Precondition failed Your request contained preconditions that were not met.
422 Unprocessable entity The content type and syntax of the request are correct, but the server was unable to process the instructions.
500 Internal server error Something went wrong on our end.

HealtheIntent API Catalog

Support

Community

The Ignite API Community on uCern is the best place to connect with Cerner engineers and other developers using the HealtheIntent APIs. Ask questions, share tips and tricks, make suggestions, and show off your work!