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 an endpoint.

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

You can create and manage auth credentials via the Redox Platform 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 endpoint, or 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 an endpoint to make sure your endpoint can actually receive data like you expect. This is a helpful implementation step so that you can test your endpoints before go-live.

You only have to verify an endpoint once. An endpoint that isn't verified won't be able to receive production data. Learn how to verify an endpoint.

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