The CareFirst API Platform is following industry-standard protocols to expose CareFirst API(s) using the REST/JSON and OAuth 2.0 security protocols. API stands for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other.

The Developer needs to register their application in the sandbox to start building and testing their application. Once the application is tested in the sandbox with non-production data, the developer can promote the configuration to production and request approval. CareFirst will approve the application to connect to the production environment.

CareFirst has multiple plans like CHPCDC, CHPMD, etc. Documentation and API(s) use lines of businesses (LOB) terms. Please refer to the additional information section for more details.

CareFirst APIs are secured using the OAuth 2.0 security protocol, which is the industry-standard for applications to integrate APIs. OAuth 2.0 is an authorization framework that allows applications to obtain limited access to user information via APIs.

Additionally, all consumer applications must include an HTTP header (x-api-subscription-key) with a valid subscription key assigned to their application.

CareFirst uses OAuth 2.0 protocols for authentication since API(s) exchange Members protected health information with third party applications upon authorization from the member. To access CareFirst's API(s) in the sandbox, your application needs to use the Authorization Code grant type.

OAuth Grant Types

Authorization Code

The Authorization Code grant type is used by web and mobile apps. It is used by both web apps and native apps to obtain an access token after a user authorizes an application. Below are very high-level steps:

• The application opens a browser to send the user to the OAuth server.
• The user authenticates and grants the application access.
• The user is redirected back to the application with an authorization code.
• The application requests an access token from the OAuth server by presenting the authorization code.

Client Credentials

This flow is useful when the party that requires access to an API is a machine. This is a machine-to-machine authorization flow. In this case, the client is the resource owner, and no end-user authorization is required. An example is a CRON job as a client calling an API to do some function.

Click on the Register link from the Menu bar.

Select Developer Type and go through the registration process.

Fill in the mandatory fields and complete the account registration process.

You will be required to read and agree to the Terms of Use agreement before your registration can be completed.

The CareFirst team will review the account and take the next steps.

Note: Additional information may be requested by CareFirst if required.

Click on the Log In button from the Menu bar.

Enter your registered email address and click Continue.

You will receive an OTP (One-Time Password) code sent to your account email. Enter this OTP code and click Verify.

Upon successful OTP verification, you will be prompted to enter your password.

After entering your password, you will be logged in as a developer and can access the API Marketplace.

Note: If you don't receive the code, please check your spam folder or request a new one.

Important: By default, you should be in the sandbox environment. Please verify that you are in the Sandbox environment by checking the environment selector at the top of the screen before proceeding. All new applications should be created in the sandbox environment for testing before promoting to production.

Log in to your account and click on My Workspace.

Click on the Manage Applications card from your workspace.

Click on the New App Registration button.

Fill in all the required information for the application, including application details, URIs, contact information, and any other mandatory fields.

Submit the form to complete your application registration.

Once your application is approved for the specified API(s), you can view your credentials and begin testing in the sandbox environment.

Note: If your application requires approval, please refer to the Application Approval Process section for instructions on how to submit your approval request.

Log in to your account and click on My Workspace.

Click on the Manage Applications card from your workspace.

Locate your application from the list of registered applications and click on the Actions button.

From the Actions menu, click on Manage API(s).

On the Manage APIs page, click the Add More API(s) button to browse available APIs.

Select the APIs you want to add to your application by checking the boxes next to each API you need.

Click Add Selected APIs to proceed to the confirmation page.

Review your API selections and click Save Changes to apply these changes to your application.

Log in to your account and click on My Workspace.

Click on the Manage Applications card from your workspace.

Verify that you are in the correct environment (Sandbox or Production) using the environment selector at the top of the screen.

Locate your registered application from the list of available applications and click on the Actions button.

From the Actions menu, click on Manage Credentials.

You can now view your application credentials including client ID, client secret, and subscription key.

Note: Keep your credentials secure and do not share them publicly. Use sandbox credentials for testing and production credentials only for live applications.

Important: Ensure your application has been thoroughly tested in the sandbox environment before promoting to production.

Log in to your account and click on My Workspace.

Click on the Manage Applications card from your workspace.

Verify your application is available and approved in the Sandbox environment.

Before promoting, make sure you have all the APIs you want included in your application.

Click on the Actions button for your application and select View Application.

At the bottom of the View Application page, click the Promote Application button.

Update the application details for production including description, purpose, application URL, redirect URL(s) (if applicable) and contact details.

Click Submit to send your application for CareFirst approval for production use.

Once approved, you can switch to the production environment and access your production credentials to begin calling CareFirst APIs in the production environment.

Note: For detailed information about the approval process, please refer to the Application Approval Process section.

To get your application approved, you need to submit a request through the Contact Us form with the subject "Application Approval Request."

Once your application has been registered, approved in the sandbox, and you have received valid credentials, you can utilize the Authorization code grant type to access the APIs through your application or tools such as Postman. It's important to conduct comprehensive testing in the sandbox environment before promoting your application to production.

Please refer to the additional information section for more details about different endpoints and test data w.r.t different line of businesses or plans.

Authorization URI example. Please refer to the additional information section for lob/plan specific endpoints.

https://idp-pit.carefirst.com/fhir-oauth2/sec/{{LOB}}/authorize?aud=testaud&redirect_uri=http://localhost:8080&state=qwertyuop&scope=openid&client_id={{client_id}}&response_type=code

Below parameter value needs to be changed

• Replace {{LOB}} with lob name you plan to test. Please refer to the additional information section for lob name.
• Replace {{client_id}} with your application client id.
• redirect_uri
• scopes
• state
• aud

On a successful call, you should have the authorization code in your redirect URI.

After receiving the application credentials and the authorization code, send a post request against the Access Token endpoint using the URL, headers, and body content below. Please refer to the additional information section for lob/plan specific endpoints.

URL

POST https://idp-pit.carefirst.com/fhir-oauth2/pub/{{lob}}/token

Headers

Body

Once your application has been registered, approved in the sandbox, and you have received valid credentials, you can utilize the Client Credentials grant type to access the APIs through your application or tools such as Postman. It's important to conduct comprehensive testing in the sandbox environment before promoting your application to production.

Once you have received the application credentials, please proceed to send an HTTP POST request to the access token endpoint. Ensure to include the specified parameters in the HTTP body.

Headers

Body

Before moving to production, ensure your application has been thoroughly tested in the sandbox environment with all required APIs and functionality.

Once testing is complete, you can promote your application to production by following the steps outlined in the Promote application to production section.

After successful promotion and CareFirst approval, you can begin calling CareFirst APIs in the production environment using your production credentials.

Important: Production APIs handle live data and require proper approval before access is granted. Make sure your application meets all security and compliance requirements.

CareFirst Line of Businesses implementing CMS Interoperability mandate

CMS Interoperability mandate API(s) implemented by LOB(s)

Credentials of test users in sandbox for testing Patient Access API

Sandbox Well-Known /Smart Configuration Patient Access API Endpoints

Sandbox Patient Access API Endpoints

Sandbox Well-Known /Smart Configuration Payer Access API Endpoints

Sandbox Payer Access API Endpoints

Sandbox Well-Known /Smart Configuration Provider Directory API Endpoints

Sandbox Provider Directory API Endpoints

Production Well-Known/Smart Configuration for Patient Access API Endpoints

Production Patient Access API Endpoints

Production Well-Known/Smart Configuration Payer Access API Endpoints

Production Payer Access API Endpoints

Production Provider Directory API Endpoints

You may get help by using the FAQ, Contact Us and Documentation pages from the Help Center.

If you have a question or need additional assistance, please reach out to our team by using the Contact Us form located in the Help Center.