Authentication is the process of proving your system’s identity to Redox. Before you can send data, you must authenticate to establish a secure, trusted connection.
You can use these authentication methods for these communication method types:
Communication method
How to authenticate
API
OAuth API key (recommended) or legacy API key
SFTP
Username and password assigned by the SFTP server
MLLP
VPN configuration
Why is authentication necessary?
Think of authentication like a digital secret handshake. By presenting valid authentication, your system tells Redox, “I am who I say I am, and you can trust the data I’m about to send.”
This process is essential for securing protected health information (PHI) and ensuring data is only sent from authorized sources.
How API authentication works
An OAuth API key includes an ID and a public key/private key pair. A legacy API key includes an ID and a secret value. The IDs are assigned by Redox, and you can generate a private key/public key pair or secret value in the Redox dashboard.
When you send an authentication request with the correct private key or secret value, we generate an access token that’s good for 5 minutes. The access token allows you to initiate requests (e.g., SEND or REQUEST).
Keep your secrets safe
You should keep your private key or secret secure. Don’t ever expose these values to a client with your production data.
Two methods of API authentication
You have two options for authenticating your API requests:
An OAuth API key relies on the following standards to authorize your system (instead of an individual user and source) to Redox:
OAuth 2.0
JSON web token (JWT)
SMART backend services.
Redox verifies the stored information in the JWT, which means staff or device changes won’t affect authorization requests.
Pro tip: JWT is an implementation of SMART backend services authorization. Any tools that conform to SMART backend services should work with this authorization method. Learn more about SMART backend services authorization.
We support the OAuth method for all of our available APIs, but the scopes are different:
Redox FHIR® API and Redox Data Model API: These APIs use organization-level keys, meaning authorization and resulting permissions are based on the organization or system. Learn how to authenticate an OAuth API key.
Redox Platform API: This API uses user-level keys, meaning authorization and resulting permissions are based on the individual requesting user. Some API functionalities might be restricted, depending on the individual user’s permissions. Learn how to authenticate a user-level API key.
Where to find OAuth API keys
There are two places to manage OAuth API keys in the Redox dashboard. You can find organization-level API keys (for the FHIR® API or Data Model API) on the Developer > Sources page of the dashboard. Or, you can find user-level keys (for the Platform API) under the user menu settings.
Requesting new access tokens
Once you authenticate an OAuth API key, you receive an access token that’s valid for 5 minutes. You can initiate requests during that window with the access token. To continue initiating requests after that window, you must request a new access token.
We don’t support refresh tokens. However, we recommend requesting access tokens based on your traffic volume:
For low traffic, request an access token before making any API requests.
For high traffic, get as many access tokens as you need. Then, use different access tokens for multiple API requests.
Legacy API keys rely on the Redox server to store user information with a session ID and cookies to authorize user access. A legacy API key can only authorize one source.
Legacy method
This type of API key has been deprecated, so it may not be available to you if you joined Redox after 2023.
Requesting new access tokens or using refresh tokens
Once you authenticate a legacy API key, you receive an access token that validates requests from the source for 24 hours. Store your authentication token securely and use it for all requests within that 24-hour period.
We recommend requesting access tokens based on your traffic volume:
For low traffic, request a new access token after the 24-hour period expires to continue making API requests.
For high traffic, run a separate service to generate a new token with the refresh token after the 24-hour period expires. Using a separate service is best if you don’t want to disrupt routine workflows by generating a new token daily.
Refresh token
Refresh tokens are dynamic, so they change and rotate daily. They expire after 7 days of inactivity.
Pro tip: Did you know that requesting new tokens is simpler than using refresh tokens? Plus, you don’t have to worry about rotating the refresh token if it’s accidentally leaked. We recommend opting for requesting and using new tokens when possible.
Authentication for TEFCA
If using Network Onramps to connect with TEFCA, you’re responsible for using access tokens that have timeouts shorter than 1 day. Be sure to use our recommended OAuth API keys for authenticating your API requests to TEFCA. Learn more about TEFCA.
Access control with multiple API keys
We recommend having at least one API key for each environment type (i.e., development, staging, production). However, you can create multiple API keys for an environment, depending on how you want to control access. It just depends on your organization’s security practices.
For example, if two dev teams work in the same environment, it may be useful to have different API keys for each team to work in their own context.
Users in your organization can view or manage API keys depending on their assigned environment role. Learn about environment roles.
Multiple API keys for the Redox Data Model API
If using multiple OAuth API keys and sources per environment, the Meta.Source.ID field is required in all of your outgoing Redox Data Model API requests. This is because OAuth API keys are organization-level keys, not source-specific. Redox uses the source ID field to distinguish which source initiated the message to route data appropriately.
If using multiple legacy API keys per environment, the Meta.Source.ID field is optional. This is because legacy API keys are source-specific, not organization-level.
The source you use designates which region an API request is coming from. As a best practice for security, though, we recommend using a unique OAuth API key for sources in each region.
You can designate which region the API key is for in its name (e.g., Production API key – U.S.).
What to expect from responses
After receiving an access token, you’re ready to initiate requests. But initiating is just one side of the exchange.
Responses differ based on the request type. Check out these articles to learn about handling your connection’s responses or responding to requests from your connection:
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®.
