onyxOS Developer Portal Documentation

Actors

The following actors are part of (and specific to) the onyxOS Developer Portal:

• Developer : User who can create applications and submit application access requests.

• Payer : User who acts on behalf of an organization to review application access requests. Payers can also create applications and submit application access requests.

• Organization : A Health Insurance company who is a client affiliated with Onyx. A single organization comprises one or more data providers.

• Data provider : The environment under control of an organization, e.g., an organization’s test or production environments.

Developer Account Registration

To register as a developer for the Developer Portal, complete and submit the registration form.

After successfully registering an account, the user is placed into the “onyxOS Developers” organization and redirected to the following page:

Before the user can log in for the first time, the following steps must be completed:

1. A verification email will be sent to the email address provided during registration.

   Click the verification link within the email to confirm your account. This helps us verify your identity and secure your account.

2. If a United States mobile phone number was provided, a welcome text message will be sent to that number.

   Text messages are sent using SMS. Non-US phone numbers are not supported at this time.

3. The Onyx team will review your registration details.

4. Upon successful review, your account will be activated.

5. A welcome email will be sent notifying you that your account has been activated and you are able to log in.

Developer App Registration

A successful login lands the user on the dashboard homepage:

Click on the Create New Application button, which leads to the application registration form which comprises three sections:

1. Software Application Details
2. Client Details
3. Application Access Request

Required fields, including your application name, software ID and version, redirect URIs, links to your terms of service and privacy policy, are marked with an asterisk (*).

• You may choose your own Software ID, but it must be unique across the database.

• Application Type is set to Web by default. Web applications use the OAuth 2 “authorization code grant type” to get an access token to make API requests. They are confidential clients, meaning they can securely maintain credentials.

• Redirect URIs are also known as Callback URLs. This is where the server sends the user after successfully authorizing an application. Must begin with “https://” or “http://localhost”.

Click here to learn more about redirect URIs as used for applications created within the Portal.

• For URI fields** besides redirect URIs**, the protocol is optional. If no protocol is specified, “http://” is assumed. Currently accepted protocols include “https://”, “http://”, and “ftp://”.

After completing the first two sections, the next step is to choose a data provider from the dropdown menu. As a developer registering an application for the first time, your choice of data provider is limited to our sandbox environments.

You must choose at least one Implementation Guide (IG) – to learn more about IGs, have a look at our API Documentation.

After gaining some experience with using our APIs, contact us at support@safhir.io to request access to our clients’ data providers.

After successfully submitting an application access request, you will land on this page. Click “Go to Your Applications” to go back to your dashboard homepage.

Developer Dashboard Pages

By submitting an access application request, every Payer that has approval privileges for the requested data provider will be notified.

On the “Pending Approval” page, you will see all your applications that have not yet been approved. Click anywhere in the field of a particular application to reveal additional details and functionality.

The “Clone Software” button leads to the application registration form with the existing app details pre-filled (except a new Software ID), allowing you to quickly make another access request to a different data provider, making none or minor changes to the app details.

The “Registration Details” button opens a modal that contains all the information provided your application. Payers who have approval privileges for the requested data provider will also be able to review these details.

When your application gets approved, you will receive an email notification.

On the “Your Approved Software” page, you will see all the applications you created that have been approved.

The “Remove Software Approval” button removes the application registration from the data provider and removes the application from the portal.

The “Application Credentials” button opens a modal that contains the client ID, client secret, and other credentials that are required to connect to the onyxOS APIs.

Simply left click within any field to copy to the clipboard.

Payer App Access Approval

As a Payer, you have an additional “Approve Software” page on your dashboard. On this page are all applications yet to be approved in the data providers that you have approval privileges for.

Payers can review each application’s registration details and choose to approve or reject the request.

The approval action registers the application in the data provider’s backend and retrieves the registration credentials. These credentials are then used to authenticate with the data provider when attempting to retrieve data.

Selecting either to approve or reject will refresh the page and after a few seconds a confirmation message will appear under the navigation bar.

Notes:

• Since Payers can also create applications and submit access requests, the same application may appear in both “Approve Software” and “Pending Approval” pages at the same time.
• An application that a Payer approves will not appear in their “Your Approved Software” page unless they were the one that created the application.
• An application approval/rejection generates an email notification to the application creator. The email does not contain any identity information about the Payer who approved/rejected the application.

The approved application will be added to the master list of approved applications, which is displayed on the APPS page.

Payers can view application credentials and remove software approval for applications created in the data provider(s) for which they have approval privileges.

Payer Account Approval by POC

Creating and approving a Payer account:

1. An organization provides the name, email, and phone number for the user that they intend to act in the Payer role on the Developer Portal.

2. The Onyx administrator creates the account with the provided details.

3. The Payer receives the following at their provided email address:

   • a verification email
   • a password reset email

4. Each organization has a point of contact (POC). The POC, acting for the organization that the Payer is registered for, will log in to the Portal and approve the Payer account.

5. An approval confirmation email will be sent to the Payer.

Developer Sandbox access

The credentials for a particular application include client ID, client secret, authorization URI, token URI, onyxOS base URI, redirect URIs, and scopes.

There are a few ways to execute the OAuth 2.0 flow to access the Developer Sandbox – the following steps describe one method using a browser and curl:

1. Request authorization code

Construct a URL with the following format in a text editor:

<<ONYSOS_BASE_URI>>&response_type=code&client_id=<<<YOUR_CLIENT_SECRET>>
&redirect_uri=<<YOUR_REDIRECT_URI>>&scope=<<YOUR_SCOPES>>

For example, your URL might look something like this:

https://api-dmdh-t32.safhir.io/v1/authorize?aud=https://api-dmdh-t32.safhir.io/v1&response_type=code&client_id=9ce0c09c-692f-4b7f-9aba-53db99f722f0&redirect_uri=https://www.google.com&scope=launch/patient fhirUser openid offline_access patient/List.read

If more than one redirect URI was registered for your application, you can use any one of them. Each scope within the scope parameter must be separated by a space as shown.

Enter your URL into a browser. You should be redirected to the following login page.

Log in using the credentials for one of our test accounts.

Upon successful login, your browser will take you to the redirect URI. Within the URL body, the state and code parameters are included. For example, if your redirect URI is https://www.google.com, the URL may look like this:

https://www.google.com/?state=y1FrnAVa1aN1MrF9Rpr4Qtv0D1g4zP&code=eyJraW QiOiJ6SlVMZ2VILTRXczM5RkZMWllxd0x1VS1Yd0xOT1RXdmlKMDRqVmNZcmQwIiwidmVyIjoiMS4wIiwiemlwIjoiRGVmbGF0ZSIsInNlciI6IjEuMCJ9...(more not included)

Take note of the code parameter, which will be used in the next step.

2. Get access token

Using curl, run this command in the terminal using your corresponding application credentials.

curl --location --request POST \
--url '<<YOUR_TOKEN_URI>>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri=<<YOUR_REDIRECT_URI>>' \
--data-urlencode 'code=<<YOUR_CODE>>' \
--data-urlencode 'client_id=<<YOUR_CLIENT_ID>>' \
--data-urlencode 'client_secret=<<YOUR_CLIENT_SECRET>>'

In exchange for your credentials, the authorization server returns your access token in the access_token field as shown in this sample response:

{
"access_token": "eyJhbGciOiJSUzI1Ni...rm8xA",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJhbGciOiJSUzI1NiIsInR5c...WuQ0w",
"patient": "7cf077e8-4e55-42d0-ae95-5e225511ab43",
"scope": "patient/Coverage.read patient/ExplanationOfBenefit.read patient/Organization.read patient/Patient.read",
"refresh_token": "eyJraWQiOiJ6SlVMZ2VIL...t9wCQ"
}

The access token will expire in 3600 seconds (1 hour) from when the response was generated.

3. Make API calls

You must include this access token in the Authorization header with the Bearer authentication scheme in every subsequent API call, as shown in this sample request:

curl --location --request GET \
--url 'https://api-dmdh-t32.safhir.io/v1/api/carin-bb \
/ExplanationOfBenefit' \
--header 'Authorization: Bearer <<YOUR_ACCESS_TOKEN>>

See the API Documentation for further guidance, which includes our Postman Collections.

Developer Sandbox test accounts

Here are a set of test users with passwords: