To successfully receive data, your destinations (or endpoints) 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.
You may prefer to use a Virtual Private Network (VPN) instead of a public destination. However, we don’t support HTTPS over VPN.
HTTPS validates the machine name we’re talking to by checking the machine name against the name in the certificate provided with the TLS handshake. It also creates an ad-hoc encryption for the duration of the data exchange. Since our VPNs don’t use machine names, we can’t verify that the machine on the other side is the one we want to connect to. This means the TLS handshake fails.
If your (or your client’s) data center is an on-prem installation and you want to use Redox APIs, you must have a public endpoint available for the HTTPS requests from Redox. We recommend using an endpoint in your perimeter network (i.e., DMZ network) rather than an endpoint in your production network.
Alternatively, we do support SFTP over our VPN (i.e., FTP over an SSH tunnel) when Redox initiates the SFTP connection to deliver or poll for files.
However, we don’t support FTPS (i.e., FTP over TLS) because it has the same verification issue as HTTPS over our VPNs.
Learn more about SFTP and FTPS.
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:
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 an authenticated data exchange.
Any incoming message with a verification token should have a header like this:
If the verification token doesn’t match, it means it’s not from Redox, so you should discard the request without processing it.
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 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: