Authenticating incoming data

To successfully receive data, your endpoints (or destinations), must:

• be publicly accessible from the internet;
• accept POST requests;
• use SSL/TLS encryption (not relevant to development environments); and
• authenticate or verify every incoming request.

Learn how to create a destination.

Just like you authenticate your system to Redox, it's a good practice to authenticate or verify data coming in to your system (i.e., data coming from Redox). You can use either auth credentials or verification tokens to do so.

You can link an auth credential to your destination to authenticate data coming in to your system from Redox. This is an advanced security option and our recommended method of verifying incoming data.

If your system supports authentication for incoming requests (e.g., OAuth, JWT), you can use auth credentials to tell Redox how to authenticate itself to you. There are different methods for authenticating Redox, which are called auth strategies. You can create auth credentials with any of these supported auth strategies:

• AWS Signature Version 4 (AwsSigv4)
• Google Workload Identity Federation (WIF)
• OAuth 2.0 2-legged
• OAuth 2.0 2-legged with JWT Bearer for GCP
• SMART Backend
• JWT Bearer

Create an auth credential in the dashboard or refer to these Platform API endpoints to manage via API:

• Create auth credential
• Update auth credential
• Delete auth credential

An access token authenticates your outgoing data to Redox; a verification token authenticates data coming in to your system. This is a basic security option.

Checking the verification token ensures that your system only processes data legitimately received from Redox. Before processing any incoming message, we recommend that you verify its legitimacy. You do this by checking that the verification token matches the one you gave to Redox.

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

Any incoming message with a verification token should have a header like this:

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.

Each destination in your system must be verified before you can receive data. This is different from verification tokens, which verify an individual message.

You must verify a destination to make sure you can actually receive data like you expect. This is a helpful implementation step so that you can test your destinations before go-live.

You only have to verify a destination once in the final step of the destination wizard. A destination that isn't verified won't be able to receive production data. Learn about verifying a destination.

Your responses to incoming API requests should differ based on the request type and the requirements of your connection's EHR system. Check out these articles for specifics:

• Responding to asynchronous events
• Responding to queries