Log In
Step 1: Generate an Authorization Code
To test out the Blue Cross and Blue Shield of North Carolina (Blue Cross NC) API, you must first generate an authorization code and a sample token that represents a member granting consent.
Below are few details you will need for generating the code:
Client ID: AJMP7iHHEfegyn2PMzTj
Client Secret: OHBJ8Pl9I2ilDZ5gRY74
RedirectURL: https://oidcdebugger.com/debug
Scope:
clinical openID FHIRUser
1. Invoke the “Authorization Code” request from a browser using below syntax:
https://oauthp2psb.bcbsnc.com/CMSP2PMemberSB/sps/oauth/oauth20/authorize?response_type=code&client_id=AJMP7iHHEfegyn2PMzTj&redirect_uri=https://oidcdebugger.com/debug&scope=openid%20read%20profile%20clinical&state=test123
2. You will be redirected to a disclaimer page. Review and click "I Understand" if you wish to proceed.
3. You will be redirected to a Blue Cross NC login screen. Log in with one of the synthetic beneficiary accounts.
4. Synthetic Beneficiary Accounts
The following test user accounts can be used for authentication and authorization:
| SubscriberID | MemberCode | FirstName | LastName | DOB | Zipcode |
|---|---|---|---|---|---|
| YPPJ12695646 | 01 | BCNCFIRSTTHREE | BCNCLASTTHREE | 06/06/1944 | 27030 |
5. After successful member authentication, you are presented with a screen to indicate if you are accessing data for “Self” or as a “Personal Representative.”
6. You are redirected to the “Authorization / Consent page.”
- If Personal Representative option is selected, you will need to choose from one of the options below in order to proceed to the “Authorization / Consent page.”
- Parent or guardian of a minor
- Active healthcare power of attorney
- Court ordered guardianship
- Other
- You will be presented a text field entry to enter the full name.
- If the option "Other" is chosen, you are presented with a text field entry to enter the relationship to the member.
- Click “Next” to proceed to the “Authorization / Consent page.”
7. Need to review the “Authorization / Consent page” and scroll to the bottom of the screen to click “I Agree” in order to “Authorize.”
8. You will be redirected to your app's redirect screen and the "Authorization code" will be sent in the response URL. The "Authorization code" is valid for 1 hour.
Step 2: Generate a sample token
Access Token URL:
https://oauthp2psb.bcbsnc.com/CMSP2PMemberSB/sps/oauth/oauth20/token
Example using curl syntax:
curl -v -k -H "Content-Type: application/x-www-formurlencoded;charset=UTF-8" -d"grant_type=authorization_code&code=[Insert_Auth_Code]&redirect_uri=[Insert_Redirect_URL]&client_id=[Insert_Client_Id]&client_secret=[Insert_Client_Secret]&state=test" https://oauthp2psb.bcbsnc.com/CMSP2PMemberSB/sps/oauth/oauth20/token
State: An optional value that you may use in your app.
Response
{
"access_token":
"eyJraWQiOiJ3QThGR3hrM3pWa1FrYU9qUW11aWxTTlJGUWp2bHNzaTJna",
"patient": "2657",
"scope": "clinical read openid profile",
"id_token": "eyJraWQiOiJ3QThGR3hrM3pWa1FrYU9qU",
"token_type": "bearer",
"expires_in": 86399
}
The response will contain a “Patient ID” that needs to be used as a search criteria for API data requests.
Step 3: Try a sample API
Try this out in Postman:
1. From the Postman app, open a new tab.
2. Paste the Request URL:
With the access token, you can use Curl to make queries as follows:
curl --header "Authorization: Bearer YOUR TOKEN HERE"
https://apiservicessb-ext.bcbsnc.com/fhir/sb/R4/payer-topayer/Patient/<FHIRPatientId>/$everything
NOTE: When a beneficiary is authorizing your application, they will not be presented the choice to select any scope. Only the app has the ability to choose what scope is required when making a request for the token.
3. Click “Send” and see the synthetic beneficiary’s personal health information as a Patient FHIR Resource display under “Body” in Postman.
Step 4: Configure your app to enable connectivity to Blue Cross NC with the following Authorization endpoint and the set of static ClientId and ClientSecret:
Auth URL:
https://oauthp2psb.bcbsnc.com/CMSP2PMemberSB/sps/oauth/oauth20/authorize
Client ID: AJMP7iHHEfegyn2PMzTj
Client Secret: OHBJ8Pl9I2ilDZ5gRY74
Step 5: Accessing Synthetic Data In order to access the full synthetic dataset for an individual synthetic beneficiary, you can do the following:
1. Set up your sandbox application.
Access the authorization url at:
https://oauthp2psb.bcbsnc.com/CMSP2PMemberSB/sps/oauth/oauth20/authorize/
Note: The last backslash is important. Also remember to append ?client_id={yourclient_id assigned to the application you registered}
2. You will be redirected to the Blue Cross authentication screen. DO NOT ACCESS THIS PAGE DIRECTLY.
3. The following test user account can be used for authentication and authorization:
Synthetic Beneficiary Accounts
| SubscriberID | MemberCode | FirstName | LastName | DOB | Zipcode |
|---|---|---|---|---|---|
| YPPJ12695646 | 01 | BCNCFIRSTTHREE | BCNCLASTTHREE | 06/06/1944 | 27030 |
4. Approve access for your application, which will now receive an access token, which can be used in the requests described above.
5. The authorization completes when you are redirected back to the Redirect_URI you specified when you registered your application.
FAQ
Authorization
To use the Blue Cross NC OAuth 2, a developer must register their application.
A registered application is given a client ID and a client secret. The secret should only be used if it can be kept confidential, such as communication between your server and the Blue Cross NC API. Otherwise the Client Application Flow may be used.
NOTE: For sandbox environment, static clientId, clientSecret will be shared. This is registered by Blue Cross team internally with a static redirect URL and will need to be configured by the client in order to initiate authorization request.
Scopes
Access tokens have a scope, which defines what the access token can do and what resources it can access. For our purposes, scopes are primarily utilized to give beneficiaries more granular choice over what data they would like to share with applications. The Blue Cross NC API has implemented a default scope to restrict read & write access to only the clinical resources as defined by HL7:
Clinical/*.*
From the OpenID Connect specification we support:
profile
This gives access to the fhir/sb/R4/payer-to-payer/UserInfo Endpoint.
Our implementation gives apps the ability to choose OpenID scope.
If the beneficiary declines to share information that your application needs to function, you may display a message explaining why that information is needed and request reauthorization or handle the collection of that information elsewhere within your application.
The default selection when a beneficiary reaches the authorization screen will be to share all data, including demographic data, with your application. If a beneficiary makes a selection as to whether or not they want to share demographic data with your application and later decides they want to change that selection, they'll need to be taken through the authorization flow again to make a different choice from the OAuth screen.
Native Mobile App Support
Native Mobile App Support follows the RFC 8252 - OAuth 2.0 for Native Apps authentication flow utilizing the PKCE extension and enables a custom URI scheme redirect.
The implementation of the RFC 8252 specification enables developers to build mobile applications without requiring a proxy server to route redirect calls to their mobile app.
The PKCE extension provides a technique for public clients to mitigate the threat of a “man-in-the-middle” attack. This involves creating a secret that is used when exchanging the authorization code to obtain an access token.
PKCE uses a code challenge that is derived from a code-verifier. The standard supports two styles of code challenge:
- plain
- S256
Redirect_URI
When registering an Application, a redirect URI is required. This is the API endpoint on your system that receives the callback from the Blue Cross NC API after a beneficiary is passed to the Blue Cross NC API to authorize your application.
Web Application Flow
To use this flow, your application should be registered with Client Type set to confidential and Grant Type set to authorization-code.
Core Resources
Base Request URL:
https://apiservicessb-ext.bcbsnc.com/fhir/sb/R4/payer-to-payer
FHIR Resources:
- All Clinical resources as defined in DaVinci IG - http://hl7.org/fhir/us/davincipdex/toc.html
Note : Patient/<FHIRID>/$everything is supported and will need to be used by clients to initiate data request and receive a bundle response. Individual FHIR resources are not supported.
UserInfo:
- Get User Profile from an Authorization Token.
FHIR Resource Bundle
/fhir/sb/R4/payer-to-payer/Patient/2657/$everything
The above URL returns all of the beneficiary’s clinical records as an FHIR Resource Bundle.
curl --header "Authorization: Bearer AUTHORIZATION TOKEN"
"https://apiservicessb-ext.bcbsnc.com/fhir/sb/R4/payer-topayer/Patient/2657/$everything"
That API call will return a bundle that contains many FHIR resources and is typically thousands of lines long.
{
"resourceType": "Bundle",
"id": "989f6d15-43e9-429f-97a5-93de5dc1e89b",
"meta": {
"lastUpdated": "2021-11-22T20:24:03.946-05:00"
},
"type": "searchset",
"link": [
{
"relation": "self",
"url": "https://apiservicessb-ext.bcbsnc.com/fhir/sb/R4/payer-topayer/Patient/2657/$everything"
}
],
"entry": [
{
"fullUrl": "https://apiservicessbext.bcbsnc.com/fhir/sb/R4/payer-to-payer/Patient/2657",
"resource": {
"resourceType": "Patient",
"id": "2657",
"meta": {
"versionId": "2",
"lastUpdated": "2021-11-22T14:53:07.885-05:00",
"source": "#PuvVum8uEowtNfhY",
"profile": [
"http://hl7.org/fhir/us/carinbb/StructureDefinition/C4BB-Patient",
"http://hl7.org/fhir/us/core/StructureDefinition/uscore-patient"
]
},
"identifier": [
{
"type": {
"coding": [
{
"system":
"http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MB"
}
]
},
"system":
"http://bluecrossnc.com/fhir/memberidentifier",
"value": "J1269564601"
}
],
"name": [
{
"family": "BCNCLASTTHREE",
"given": [
"BCNCFIRSTTHREE"
]
}
],
"gender": "female",
"birthDate": "1944-06-06",
"address": [
{
"line": [
"23 WESTERN ST"
],
"city": "MOUNT AIRY",
"state": "NC",
"postalCode": "27030"
}
]
},
"search": {
"mode": "match"
}
},
{
"fullUrl": "https://apiservicessbext.bcbsnc.com/fhir/sb/R4/payer-to-payer/Provenance/4e44a0f0-e723-3f1b-a6dea3f5023630d0",
"resource": {
"resourceType": "Provenance",
"id": "4e44a0f0-e723-3f1b-a6de-a3f5023630d0",
"meta": {
"versionId": "1",
"lastUpdated": "2021-08-04T08:58:05.801-04:00",
"source": "#sAN2NtgMboFqXbTd",
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/uscore-provenance"
]
},
"target": [
{
"reference": "Patient/2657",
"identifier": {
"type": {
"coding": [
{
"system":
"http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MB"
}
]
},
"value": "J1269564601"
}
},
{
"reference": "Condition/26efcfd2-acfb-31bb-b2feb48574ff188f"
},
{
"reference": "Procedure/6dac3a0e-283b-3a37-a1aab98214efa5ef"
}
],
"recorded": "2018-10-10T00:00:00.000-04:00",
"agent": [
{
"type": {
"coding": [
{
"system":
"http://terminology.hl7.org/CodeSystem/provenance-participant-type",
"code": "author"
}
]
},
"who": {
"reference": "Organization/BCBSNC"
}
}
]
},
"search": {
"mode": "match"
}
}
... this is only a subset of the entire output ...
Get User Profile for an Authorization Token
HTTP GET /connect/userinfo
The UserInfo Endpoint is an OAuth 2.0 Protected Resource. The above URL fetches the fictitious beneficiary’s basic account information given an Authorization Token. This is most often used when creating an account within your application. An HTTP GET is called and the response is returned as JSON.
curl --header "Authorization: Bearer AUTHORIZATION TOKEN"
"https://apiservicessb-ext.bcbsnc.com/v1/connect/userinfo"
{
"sub": "fflinstone",
"prefered_username": "fflinstone",
"given_name": "Fred",
"family_name:, "Flinstone,
"name": "Fred Flinstone",
"email": "pebbles-daddy@example.com",
"created": "2017-11-28",
"patient": "123456789",
}
Blue Cross and Blue Shield of North Carolina does not discriminate on the basis of race, color, national origin, sex, age or disability in its health programs and activities. Learn more about our non-discrimination policy and no-cost services available to you.
Information in other languages: Español 中文 Tiếng Việt 한국어 Français العَرَبِيَّة Hmoob ру́сский Tagalog ગુજરાતી ភាសាខ្មែរ Deutsch हिन्दी ລາວ 日本語
© 2024 Blue Cross and Blue Shield of North Carolina. ®, SM Marks of the Blue Cross and Blue Shield Association, an association of independent Blue Cross and Blue Shield plans. All other marks and names are property of their respective owners. Blue Cross and Blue Shield of North Carolina is an independent licensee of the Blue Cross and Blue Shield Association.