No one answers the phone when they don’t recognize the number on the screen. Unless you ordered food delivery, in which case you take a chance lest the delivery person needs help finding you. But generally, we swap phone numbers and send a text to someone we actually want to talk to so that they know it’s us when we want to communicate with them later. In other words, you’re authenticating your identity.
But what happens when you change your phone number? Simple, you send another text to confirm your identity with a new phone number.
Authenticating your configuration with Redox is similar in concept: we want to make sure it’s you on the other end of that call, and we do this by giving you an API key and secret. Secret values are how your system proves its identity to us.
First, you plug in the API key and secret in the Redox dashboard. Then, when you send an authentication request with these values, we generate an access token for you that’s good for 24 hours, which allows you to freely initiate requests and receive data back.
Authenticating your system is specifically for SEND and REQUEST type of requests.
We recommend having an API key and secret for each environment. For most systems, this means having one each for development, staging, and production.
However, you have the flexibility to create more than one API key and secret for a given environment, depending on how you want to control access. This depends on your unique security practices. If, for example, you have two development teams working in the same environment, it may be useful to have an extra key and secret so that the keys can be used within the context of one development team.
But it’s your call on how many keys to use—yes, you’re welcome for that unintentional, but delightful pun.
Your API key and secret should be kept secure and should never be exposed to a client for production data.
If you decide to use multiple API keys per environment type, the Meta.Source.ID field is required in any of your outgoing API requests with the Data Model API. This is required since OAuth API keys are organization-level keys, not system-specific, and Redox needs to be able to distinguish which system initiated the message to route it appropriately.
If you're using multiple legacy API keys per environment type, the Meta.Source.ID field is optional since the legacy API keys are inherently specific to a given system anyways.
You have two options for authenticating your configuration with Redox.
Our preferred API key relies on these standards to authenticate your system: OAuth 2.0, JSON web token (JWT), and SMART backend services. This type of API key authorizes your system to use Redox rather than authorizing only one user and their initiation point. This means you could have staff or device changes, but it won't matter because the JWT contains your information, which the Redox server verifies. In this case, the user information is stored in the JWT instead of the server.
If you want more of a conceptual summary, learn how OAuth works or watch this YouTube tutorial on JWT. Or, if you're familiar with the basics of JWT but you need more of a technical reference, check out this Request for Comments (RFC) on JWT.
And just a tip: JWT is an implementation of SMART backend services authorization, so any tools that conform to SMART backend services should work with this authorization method. Learn more about SMART backend services authorization.
This authentication method is supported for the Redox FHIR® API, the Redox Data Model API, and the Redox Platform API. The only difference between authorizing these APIs with OAuth is that we use organization-level keys for the FHIR® API / Data Model API and user-level keys for the Platform API. Organization-level keys mean that your authorization and functionalities are based on the organization or system instead of the unique user. Whereas user-level keys mean that your functionalities with the API may be restricted depending on your unique user permissions.
Learn how to authenticate an OAuth API key.
There are two places to manage OAuth keys in the Redox dashboard. You can find organization-level keys (for the FHIR® API or Data Model API) on the Developer tab of the dashboard and user-level keys (for the Platform API) under the user menu settings.
Once you authenticate an OAuth API key, you receive an access token that's valid for 5 minutes. You can initiate calls during that window with the access token, but if you need to continue initiating calls, you must request a new access token.
We don't support refresh tokens. If you have low traffic, we recommend requesting an access token before making any API request. But if you have higher traffic, you can get as many access tokens as you need, so you could use different access tokens for multiple API requests.
Alternatively, you can individually authenticate every API key for your system with our legacy method, which relies on the Redox server storing your user information with a session ID and cookies to authorize your use of Redox. This is a deprecated method, so it may not be available to you if you're new to Redox.
This authentication method is currently supported for the Redox Data Model API. With this method, keep in mind that you must authenticate the API key you want to use before initiating requests with it.
Learn how to authenticate a legacy API key.
Once you receive an access token with the legacy method, your system is successfully authenticated. We recommend that you securely store your authentication token and use it for all of your calls within that 24-hour period.
If you have low traffic, you can do this process, then generate a new authentication token the next time you want to initiate a call.
If you have high traffic, you can have a separate service running that generates a new token with the refresh token whenever the previous one expires. This is best when you don’t want to worry about generating a new token every day so that your routine workflows aren’t disrupted.
Once you complete your authentication and receive an access token, you're ready to initiate and receive requests. Responses to your requests differ based on the type of request made and whether you require a response from your partner’s EHR system. Learn more about: