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. Fill out the request form with the following information:

Once the new account is approved, work with your HealtheIntent Engagement Leader or submit an eService ticket to request that the account be granted access to the appropriate APIs and resources.

Making OAuth Calls

This section provides basic steps for accessing protected APIs using a two-legged OAuth 1.0a authentication flow. Since this flow is less common than three-legged authentication, you should test making an OAuth call using a browser or curl before writing any code. This will help you get familiar with the fundamentals of two-legged authentication before using any third-party libraries, many of which are optimized for the three-legged flow and may be difficult to use with the two-legged flow. See Cerner’s OAuth specification in the Reference Pages on uCern Wiki for more information about the authentication flow below.

Prerequisites

Retrieving an access token

Make an HTTPS POST to the OAuth access token URL as follows:

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.

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!