Authentication methods

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.

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

Keep your secrets safe

Your API key and secret should be kept secure and should never be exposed to a client for production data.

Authentication methods

You have two options for authenticating your configuration with Redox.

Authenticate with JWT

First, you can use a JSON web token (JWT) to authenticate your system to initiate requests. This type of authentication is intended to authorize your system for use with 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.

Learn more about JWTs

Curious to learn more about what a JWT is or how it works? 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 currently supported for the Redox FHIR® API and the Redox Platform API. The only difference between authorizing these APIs with JWT is that we use organization-level keys for the FHIR® API and user-level keys for the Platform API. Organization-level keys mean that your authorization and functionalities are based on the organization 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 with JWT.

Authenticate an API key

Second, you can individually authenticate every API key for your system. This method relies on the Redox server storing your user information with a session ID and cookies to authorize your use of 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 an endpoint.

Refreshing your access token

For either authentication method, you receive an access token when 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.

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 partner’s EHR system. Learn more about what kind of responses to expect for these types of requests:

Try it out

Are you interested in a hands-on exploration of initiating requests and receiving responses? Build your own prototype and start testing with digital record retrieval.