Authenticate an OAuth API key

If you haven’t already, check out our authentication overview. This article contains instructions for how to authenticate your system with our recommended API key.

Let's start with the high-level steps:

  1. Provide your public key to Redox.
  2. Request an access token from Redox with an auth request.
  3. Store the access token in your own system.
  4. Initiate any API request with the access token in the header.

Check out the diagram for a visual version of these steps:

OAuth flow
OAuth flow

Now let's get into the nitty gritty for each step.

Provide your public key to Redox

First, you have to have an API key with a private/public key pair.

  1. Log in to the dashboard.
  2. From the navigation menu, select the Developer page.
  3. By default, the Developer page opens and displays the API Keys tab.
  4. Any created API keys display. The top section contains OAuth keys and the bottom section contains legacy keys. To create a new API key, click the Create API Key button. If you already have an API key created and only need to configure it, click the Edit button of the API key that you want to configure, then skip to step 7.

    Platform API keys

    If you're using the Redox Platform API, you need to create a user-level API key instead. Navigate to the user-level API key page to create and manage Platform API keys.

  5. A modal opens with the API key details. In the Name field, enter the API key name.

    Options for legacy customers

    If you're an existing user with legacy keys, you may also see radio buttons display for Legacy and OAuth options. If these are visible, select the OAuth radio button.

  6. Click the Add button.
    Create an OAuth API key
    Create an OAuth API key
  7. By default, the Settings page of the newly created API key displays with the details. The Name field displays the API key name you entered previously. The client ID field shows the automatically generated ID for the API key. Copy and store the client ID to use when retrieving an access token. Then, choose one of the following options to complete.

Request and store an access token

Next, you must request an access token with an auth request. There are two options for this:

  • Use our Postman collection; or
  • Use an application of your choice.

Either way, the authentication steps are the same. If you choose to use Postman, complete the prep steps. Otherwise, skip to the authentication steps.

Postman prep

For Postman, there's a little bit of setup to do before running the authentication requests.

  1. From the Settings tab of the API key, click the DevTools (Postman) tab.
  2. The Postman options display. Click the Download Postman collection button.
  3. Run the authentication collection in Postman and select the option for how you want to run it: Postman for Web or Postman for Mac.
  4. Postman opens and automatically imports the collection. The collection is named Redox Platform Authentication but you can also use it for authenticating requests sent via the Redox FHIR® API or the Data Model API.
  5. If you haven't already downloaded the Postman environment when you were generating keys, click the Download Postman environment button from the DevTools tab.

    Note about the private key

    If you download the Postman environment from the Settings tab (when you're generating keys), the value of the private key automatically populates. But if you download the Postman environment from the DevTools tab instead, the private key is empty. Make sure to manually enter the private key in the Postman environment if you download it at this step.

  6. In Postman, click the Environments tab.
  7. Click the Import button.
  8. From the file explorer, select the Postman environment that you just downloaded.
  9. The Postman environment is added. Select the environment name in the left-hand pane or in the Environment drop-down.
  10. If the private key variable is still empty, enter the private key that you generated previously.

    JWKS URL

    If you provided your public key with a JWKS URL, you also need to populate the kid value.

Now that Postman is ready, you can proceed to the auth request steps.

Send an auth request

  1. Generate a signed request in your system using your private key.
  2. Send an auth request with the signed assertion to https://api.redoxengine.com/v2/auth/token via HTTP POST from your system. Check out the Header and parameter definitions below these steps for explanations of the header and parameter values.

    Canada URL

    If you're operating in Canada, you must tweak the Redox hostname slightly. All you need to do is add a ca in that URL like this: https://api.ca.redoxengine.com.

    1. With Postman, the authentication request looks something like this:
    2. With your own application, the request may look like this:
      Copy the code example above and make sure the axios and jose libraries are installed with npm i axios jose. Then, update the the privateKeyPEM, clientId, and kid based on the signed request you generated in step 1.
  3. Redox validates the signature in the request using your public key, then sends back a response with the access token.
  4. Use the returned access token to make an API request to Redox.

    Expiration for access token

    Just note that access tokens expire after 5 minutes, so if a request fails, it's likely that your access token has expired.

    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.

Header and parameter definitions

In case you're interested in the definitions and expected values for header and parameters in the auth request code examples, check out the tables below. You can also view an example of a valid JWT with all of these values populated.

Initiate requests

Now you're ready to initiate API requests with the access token in the Authorization HTTP header using the Bearer authentication scheme like this: