Security and Authorization v1

Summary API Attachments FAQ CHANGE LOG     

Overview

This API was deprecated August, 2019. Clients are encouraged to use version 2, which is backwards compatible. Please refer to the v2 documentation for more information.

This documentation describes how to use the platform's original standard security API to request an access token that can be used to access other APIs on the platform.

Certain legacy APIs exposed through this platform utilize a legacy Authorization implementation described at the bottom of this summary. Review the Change Log to determine whether a given API uses the standard or legacy Authorization mechanism.

Access Control via Web Tokens

All Change Healthcare Enterprise APIs on this platform are secured using JSON Web Tokens (JWT).

Security via TLS

All calls to Change Healthcare APIs are encrypted over HTTPS. Our APIs support connections using TLS version 1.2 or higher.

Authorization via OAuth2

Access to Change Healthcare APIs is controlled via OAuth2 using the client credentials grant. This is a secure authorization workflow that allows consumers to obtain a short-lived (one hour) access token that must be transmitted with subsequent API requests.

To obtain a token, consumers first need a client_id and client_secret, credentials provided during the customer onboarding process. To request access credentials, please contact apisupport@changehealthcare.com or use the 'Contact Us' link to contact the Product Manager of a specific API.

Obtaining an access token

The following documentation describes how to get an access token in a particular environment. Note that Your-ClientId and Your-ClientSecret should be replaced with a valid set of credentials. Also note that the URL is environment-specific and may need to be modified according to the target environment.

curl -X POST \
  https://sandbox.apis.changehealthcare.com/apip/auth/v1/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<Your-ClientId>&client_secret=<Your-ClientSecret>&grant_type=client_credentials'

A successful call to this API will return a new accessToken, which can be used to authorize subsequent calls to other APIs on the platform. By default, the accessToken will be valid for one hour from the time of its issuance.

Example response:

{
   "accessToken":"eyJraWQiOiIxIiwidHlwIjoiSldUIiwiY..."
}

The access token returned in the above response can be used to access APIs on this platform that are secured via the standard Authorization implementation. Calls to these APIs must include the following headers:

Content-Type: application/json
Authorization: Bearer <Your-Access-Token>

Legacy Authorization

This section describes the process for requesting an access token from the legacy Authorization API implementation. Please refer to the Change Log to determine which APIs use this implementation.

Note that the URL is environment-specific. The production environment URL is https://apis.changehealthcare.com/apip/auth/v1/token.

curl -X POST \
  https://sandbox.developer.changehealthcare.com/apis/auth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<Your-ClientId>&client_secret=<Your-ClientSecret>'

This call will return a new accessToken that can be used to call APIs that use the legacy authorization implementation. The accessToken will be valid for one hour.

Example response:

{
   "accessToken":"eyJraWQiOiIxIiwidHlwIjoiSldUIiwiY..."
}

The access token returned in the above response can be used to access APIs on this platform that are secured via the legacy Authorization implementation. Calls to these APIs must include the following headers:

Content-Type: application/json
Authorization: Bearer <Your-Access-Token>

Is this API oAuth 2.0 compliant?

Yes. Not all grant types are currently supported, but this API is compliant with the oAuth 2.0 specification, which can be found in the attachments.

What grant types are currently supported?

The platform currently supports the client credentials grant type.

What if my API includes user context

Platform tokens are appropriate for system to system communications. For APIs where user context is required, tokens should be issued by and retrieved from the CIAM system. The API Marketplace supports issued by either of these identity providers.

What is the difference between version 1 and version 2 of this API

Version 1 of this API was designed to facilitate the migration of legacy APIs onto the platform. Versio 2 is more fully compliant with the expectations outlined in the oAuth 2.0 specification. Version 1 should not be used for new implementations. Version 2 is backwards compatible to support the migration of version 1 clients.

Change Log

API Name API Version Date Introduced Available Until
Security and Authorization v2 08/01/2019 TBD
Security and Authorization v1 04/01/2019 Deprecated

Release Notes:

v2

  • This version of the API is more fully compliant with the conventions defined in the oAuth 2.0 specification.

v1

  • Initial offering of Security and Authorization.
  • Documentation includes instructions for both the current and legacy implementations