Blue KC

Blue KC Patient Access API Developer Guide


Sandbox JWT

Obtaining a Json Web Token (JWT) requires performing an authentication step (outlined in 'Getting Started in our Sandbox). This is initiated from a specially constructed URL that requires specific information, most of which will be granted after registration and on boarding.

You will need:

The base URL looks something like:

Replace 'appId', within the URL, with the provided Client ID.

Note: You can replace the redirect_uri with something other than Make sure to encode the :// characters with %3A%2F%2F. Helpful Encoding Tool: URL Encoder.

The scope=openid%20offline_access is mandatory. Additional scopes can be appended in the URL (scopes can be requested during the onboarding process). As noted above, we recommend using the URL provided in the onboarding email, as it should include the additional scopes.

Getting Started in our Sandbox (Authorization Code and Access Token)

To get started, use the test authorization flow URL that's was provided from Blue KC, in the onboarding process.

  1. Launch the authorization process/sign in URL flow that was provided in your onboarding email.
  2. Authenticate/Authorize using the developer account credential that you created during the onboarding process.
  3. Following a successful auth, you will be routed to "redirect_uri" that was listed in the auth URL (which was provided to us via the form you completed to request onboarding/access).
  4. Once on the redirected site, look in the URL for the value of "code=ey…." (this is your authorization code).
  5. Select and copy the whole "ey…" value.
  6. You must now call the /token API to retrieve an access token for requesting member data. The /token call can be found in step 7c or in the "Sandbox Endpoints" section at the bottom of the page.
  7. We will use Postman for acquiring the access token.
    1. Open Postman
    2. Create a new call
    3. Input the test authorization API:
    4. Set the call to POST
    5. Navigate to the Authorization tab, set authorization to "No Auth"
    6. Navigate to the Body tab, and set the following
      1. Select 'x-www-form-urlencoded'
      2. code == [authorization code from step 5]
      3. client_id == [client_id provided during the onboarding process]
      4. client_secret == [client_secret provided during the onboarding process]
      5. redirect_uri == [base64 encoded redirect_uri; base64 encoding tool]
      6. grant_type == authorization_code
    7. Press Send
  8. Your return values should contain an "access_token" (see the "What is this access token?" section below for more information.)
  9. Select and copy the access_token.
  10. Navigate to our Swagger documentation.
  11. In the top right corner press "Authorize".
  12. In the Value field, input the text "Bearer [access_token]".
  13. Press Authorize.
  14. The sandbox calls are now accessible; the APIs contain the keyword 'sandbox'.
    Example: /api/v1/sandbox/FHIR/R4/[parameter]
  15. The sandbox environment has limited data and is for testing purposes only
  16. Once you are comfortable with the sandbox environment and wish to begin integration with our Production environment reach out to the Blue KC contact who provided the initial test URL. They will then provide you with the production URL.
    1. Production /token API (similarly used in sandbox step 7c):

See "Production App Configuration Resources" at the bottom of the page for the production /token API call.

What is this access token (from step 9)?

The token returns all of the standard JWT elements from Azure B2C plus some custom claims. Your code will need to understand one of these custom claims.

                "typ": "JWT",
                "alg": "RS256",
                "kid": "3keoem5aEBDxiMVwlj0zTkZ3L5hDT5wNxLwrQ8-6Juw"
                "exp": 1609449886,
                "nbf": 1609446286,
                "ver": "1.0",
                "iss": "",
                "sub": "e11bf45a-7534-db09-a68d-6410d1fef145",
                "aud": "5574853e-a0ef-45ad-9301-d94f6102e857",
                "acr": "b2c_1a_interopappdeveloperauthorizationflow",
                "nonce": "defaultNonce",
                "iat": 1609446286,
                "auth_time": 1609446286,
                "signInName": "InteropAppDev1",
                "appId": "5574853e-a0ef-45ad-9301-d94f6102e857",
                "consentedMemberNamesAndBeKeys": [
                  "KERRY REBER|90003160541",
                  "BETHANY SERNA|90001627557"
                "consentedMemberUniqueKeysAndBeKeys": [

Notice the element "consentedMemberNamesAndBeKeys"

            "consentedMemberNamesAndBeKeys": [
              "KERRY REBER|90003160541",
              "BETHANY SERNA|90001627557"

Because a patient may be capable of authorizing your app to see multiple people's information, we needed a way store in the JWT who the patient has authorized for your app.
When queries against the API need the patientId parameter you can find the allowable patient IDs in the JWT.
Each element of the "consentedMemberNamesAndBeKeys" array is a tuple (name|patientId) with | as the separator. (name|patientId) with | as the separator

Within your app this allows you to manage only one JWT, but pull data for multiple people.

Calling the API

From the JWT pull out the patientId and use that patientId in the following URLs to test that.

When setting up your tool (e.g. postman, restful, etc.) set up the headers to have "Authorization" with a value of "Bearer {jwt}". {jwt} is the base64 encode JWT that you generated in the previous step.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm...
Once you have the token set as a header for the GET call and the patientId you can try various calls


Production (once you're comfortable with our Sandbox)

For full documenation please refer to our Swagger documentation

Sandbox App Configuration Resources

You will need to understand how to configuration your application to participate in an OIDC (OpenID Connect, OAuth 2.0) authorization flow. From an OAuth perspective the flow is called and authorization flow because the person authorizes an app to make API calls using the identity of the person. The result of the flow is an identity token that that contains an access token.
The access token must be presented at the API in order to get any data returned. During the flow a standard authentication step will occur.
Additionally, just as with manually obtaining a JWT, your app must be configured with the AppID, return URLs and scope. Depending on the libraries and tools you use, different things may be asked for. Below is a complete list of URLs that your app may need to know. In particular, it should absolutely want to know the authorize endpoint.

Microsoft documentation: OAuth 2.0 authorization code flow in Azure Active Directory B2C

The sandbox authorization endpoints always return a particular set of patients irrespective of the credentials passed as long as authentication succeeds. The production endpoints will return one or more patients that the user has authorized. This may be self or other (e.g. personal representative or parent for a minor child).

Sandbox Endpoints

Production App Configuration Resources

Production Endpoints

Testing production configuration is difficult because you need a valid set of credentials from a production member to validate the workflow and return URL, JWT, etc.