Authenticating Redox APIs

Last updated: Mar 4, 2024

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 with someone we want to talk to so that they know it’s us when we text 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 Redox setup is similar in concept: We want to make sure it’s you on the other end of that call. 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 5 minutes. The access token allows you to freely initiate requests and receive data back.

Request types

Authenticating your system is specifically for SEND and REQUEST type of requests.

Using multiple keys

We recommend having an API key and secret for each environment. For most organizations, this means having one per environment type (i.e., development, staging, production).

You can create more than one API key for a given environment, though, 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 for each team to have a key and secret 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.

Ultimately, it’s your call on how many keys to use—yes, you’re welcome for that unintentional, but delightful pun.

Keep your secrets safe

You should keep your API key and secret secure. Don't ever expose a key and secret to a client with your production data.

Multiple API keys for the Redox Data Model API

If you use multiple API keys per environment type, the Meta.Source.ID field is required in any of your outgoing API requests with the Redox Data Model API. This is because OAuth API keys are organization-level keys, not source-specific. We use the source ID field to distinguish which source initiated the message to route data appropriately.

If you use multiple legacy API keys per environment type, the Meta.Source.ID field is optional. This is because legacy API keys are source-specific, not organization-level.

As a reminder, a source identifies the communication method and sending system.

Authentication methods

You have two options for authenticating your setup with Redox.

OAuth API key

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 a user and their initiation point. So, you could have staff or device changes, but it won't matter since the JWT stores your information, which the Redox server verifies.

Learn more about authentication standards

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.

Redox supports the OAuth method for the Redox FHIR® API, the Redox Data Model API, and the Redox Platform API. The only difference 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 may restrict your functionalities with the API depending on unique user permissions.

Learn how to authenticate an OAuth API key.

Where to find OAuth keys

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. Or, you can find user-level keys (for the Platform API) under the user menu settings.

Requesting a new access token

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.

Legacy API key

Receiving responses

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 connection’s EHR system. Check out these articles for specifics:

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®.