Verifying your endpoint to receive and respond

Last updated: Feb 27, 2024

Authenticating your system opens one side of the data traffic highway, so to speak. It's equally important to configure your system to receive and respond to API requests. You do this by verifying your endpoint(s). To successfully exchange data, your endpoint(s) must:

be publicly accessible from the internet;
accept POST requests;
use SSL/TLS encryption (not relevant to development environments); and
check the verification token of every incoming request.

Only for engineer or implementer roles

Any user in a given organization may view configured endpoints (or destinations). However, you must be assigned to an engineer or implementer role to verify or manage endpoints.

Verification tokens vs. access tokens

We recommend using a verification token to authenticate incoming data from Redox—just like an access token authenticates outgoing data to Redox. Checking the verification token ensures that your system only processes data legitimately received from Redox. In other words, it's like checking your caller ID before answering a phone call.

So Redox generates an access token for you to initiate requests, but your system generates a verification token for Redox to push data to you. Both tokens enable both sides of authenticated data exchange.

Before processing an incoming request, we recommend that you verify its legitimacy. You do this by checking that the verification token matches the one you gave to Redox. Learn how to configure and verify an endpoint.

What about more secure auth options?

In case you want to use a beefier security system to authenticate incoming API requests, you have the option to use custom endpoint authentication. With the Redox Platform API, you can:

Check what auth strategies are available.
Create or edit an auth credential.
Retrieve details for a destination (or endpoint) in your dashboard organization.
Update a destination's auth credential.

(Spoiler alert!) Redox supports these auth strategies for your endpoints:

Google Workload Identity Federation (WIF)
OAuth 2.0 Two-legged
SMART Backend
JWT Bearer

To manage and set up for yourself, check out these Redox Platform API specs for technical details:

To get help with setting up custom endpoint authentication without the Platform API, submit a ticket via our Help Desk.

Receiving requests

Once an endpoint is verified, you can begin receiving requests. If you want to receive data for multiple systems, you must verify each one individually. Any request you receive should have the verification token in the header like this:

Example: Verification token headers

json

1
"authorization" : "Bearer [your-verification-token]"
2
"verification-token" : "[your-verification-token]"

If the verification token doesn’t match, it means it’s not from Redox, so you should discard the request without processing.

Verification tokens for live data streams

Live data streams don't contain a challenge or verification token in the body or URL of the request. As such, you don't need to return a challenge value.

In synchronous requests, the request body contains the verification token and challenge. Once you respond with the challenge value, any additional requests only include the token (not the challenge) in the request header. You should verify the verification token to make sure it's an authorized request.

Responding to requests

The response to any request you receive differs based on the request type and the requirements of your connection's EHR system. Check out how to handle responses for:

Other required parameters

Each data model has different requirements for parameters. Explore each data model and their respective required parameters.

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.