OnyxOS Developer Registration 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 Admin : User who acts on behalf of an organization to review application access requests.

• Organization : A Health Insurance company who is a client affiliated with Onyx Health. 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” 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 verify my email address 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.

Note: You can log in only after verifying your email address.

Application Creation Flow

Patient Access API

Click on the Create New Application button a dialog will appear prompting you to select type of application you want to create. Select Patient Access API.

After selecting the Patient Access API application, you will be presented with application registration form which comprises five sections:

1. Software Application Details
2. Client Details
3. Privacy Policy
4. Data Security
5. Application Access Request

Note: Fields marked with an asterisk (*) are required. The Continue button will remain inactive until all required fields in each step are completed.

• Application ID and Application Type are pre-set by default and disabled for Patient Access API application creation.

• The Application ID is a unique auto-generated value and cannot be modified.

• The Application Type is set to Web by default. Web applications use the OAuth 2.0 authorization code grant type to obtain access tokens for API requests and are configured as Confidential Clients, meaning they can securely maintain credentials.

• Redirect URIs (also known as Callback URLs) Learn about Redirect URIs specify where the server redirects the user after successful authorization. Each Redirect URI must begin with “https://” or “http://localhost” for local development.

• After completing the first four 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 selection is restricted to our sandbox environments. Please ensure that “TEST OnyxOS Sandbox” is selected as the Data Provider.

• You must choose at least one Implementation Guide (IG). To understand more about the APIs and IGs in detail, please refer to the corresponding API Documentation.

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

Developer Dashboard Pages

After logging in, you will be redirected to developer dashboard page where you can view applications statuses under Pending Approval, Approved, Rejected, and Revoked tabs, and Clicking on each tab will navigate you to the respective page where you can view detailed application statuses.

• When you submit an access application request, all Payer Admins with approval privileges for the requested data provider will be notified.

• The Pending Approval page lists all applications that are still awaiting approval. Click on any application to view more details and available actions.

• The Clone Software button opens the application registration form with existing app details pre-filled (except for a new Software ID). This allows you to quickly create another access request for a different data provider with minimal changes.

• The Registration Details modal displays all the information provided during registration, organized into the same four tabs as seen in the application registration form. This allows You and authorized Payer Admins to review all application details in a structured format.

• When your application is approved, you’ll receive an email notification stating that your application has been approved. The approved application will appear under the Approved tab.

• The Application Credentials button opens a modal displaying the Client ID, Client Secret, and other credentials required to connect to OnyxOS APIs. Simply left-click on any field to copy its value to your clipboard.

• If your application is rejected, you’ll receive an email stating that your request has been rejected, and the application will appear under the Rejected tab.

• If an approved application’s access is later revoked by the Payer Admin, you’ll receive an email notification, and the application will appear under the Revoked tab.

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:

> <<ONYXOS_BASE_URI>>&response_type=code&client_id=<<<YOUR_CLIENT_ID>>
&redirect_uri=<<YOUR_REDIRECT_URI>>&scope=<<YOUR_SCOPES>>

• 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)

Note: 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"
}

Note: 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 '{base_url}/carin-bb/ExplanationOfBenefit' \
--header 'Authorization: Bearer <<YOUR_ACCESS_TOKEN>>

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

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

Developer Sandbox test accounts

Here are a set of test users with passwords: