Authenticate with JWT

If you haven’t already, check out our high-level summary for authentication with Redox. If you want to authenticate with a JSON web token (JWT), follow the steps below.

Supported APIs

This authentication method is currently only supported for the Redox FHIR® API and the Redox Platform API. 

Generate a public key

In order to authenticate with a JWT, you must have a key pair with a private and public key. There are two ways to get a generate a public key:

  • Generate your own JWKS URL (preferred); or
  • Generate an RSA key in the Redox dashboard.

JWKS URL

This type of URL publicly exposes the keys you use for signing your JWT. The URL can be internal to your servers or somewhere like a GitHub Gist. If you use this URL, Redox fetches the kid property in the JWT to find the right public key.

  1. Generate your own JWKS URL.
  2. Log in to the dashboard.
  3. From the navigation menu, select the Redox Labs page.
  4. The available Labs features display. On the FHIR® API Beta tile, click the Explore button.
  5. On the Redox FHIR® API screen, click the Get API Keys button.
  6. If you haven't created any keys yet, click the Create new API Key button.
  7. The New API Key modal opens. Enter a name for your new API key, then click the Create new API Key button.
  8. Your new key appears in the list of keys. Locate the key you want to use to authenticate your system and click the Public Keys button.
  9. A modal opens with two fields. In the top field, paste the JWKS URL that you generated.
  10. At the bottom of the modal, click the Save Changes button.

RSA key in the dashboard

  1. Log in to the dashboard.
  2. From the navigation menu, select the Redox Labs page.
  3. The available Labs features display. On the FHIR® API Beta tile, click the Explore button.
  4. On the Redox FHIR® API screen, click the Get API Keys button.
  5. If you haven't created any keys yet, click the Create new API Key button.
  6. The New API Key modal opens. Enter a name for your new API key, then click the Create new API Key button.
  7. Your new key appears in the list of keys. Locate the key you want to use to authenticate your system and click the Public Keys button.
  8. A modal opens with two fields. On the right side of the modal, click the Generate new keys button.
  9. The private and public keys display at the bottom of the modal. You can toggle the Show keys as PEM option to view the keys in an encoded format. Either way, copy or download the pair of keys.

    Private key

    Make sure to copy or download the private key prior to closing the modal. You can't retrieve the private key again after leaving this screen.

  10. On the same modal, click the Download Postman environment button if you want to use the Redox Postman collection and environment to speed up the authentication process.
  11. Then, at the bottom of the modal, click the Save Changes button.
  12. On the API Keys page, the Public Key column of the table displays how many public keys this key has. In the Scope column, you can click the Edit Scope button to specify which environment(s) this key should be used for.
  13. Next, copy the Client Id for your key before proceeding to retrieving an access token.

Request an access token

You have two options for requesting an access token:

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

Postman collection prep

If you choose to use Postman, there's a little bit of setup you need to do before running the authentication requests. Make sure that you downloaded the Postman environment from step #10 in the previous section.

  1. Run the authentication collection in Postman and select the option for how you want to run it: Postman for Web or Postman for Mac.
  2. Postman opens and the collection is imported automatically into your list of Postman collections. The collection is named Redox Platform Authentication but you can use it for authenticating FHIR® as well.
  3. Next, import the Postman environment file that you downloaded in step #10 in the previous section.
  4. The Postman environment is added. Click the Environments tab.
  5. In the Environment drop-down, select the Redox Postman environment option.
  6. Your available environments displays on the page. Select the Redox environment.
  7. The environment variables displays on the right. In the Variables table, add a row for your secret value. In the Variable column, enter secret_value. In in the Initial Value column, paste your secret value.

    JWK encoded secret value

    Currently, this Postman authentication collection only supports your secret if it's JWK encoded.

    If you do have a JWK encoded secret value, you can easily copy and paste it into Postman so that the keys and secret values automatically populate. To do this, copy your secret value and paste it into the "key" field in Postman.

  8. Then, click the Collections tab again. In the Environment drop-down, select the Redox environment option to populate the environment variables.

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

Authentication steps

To give you an overview of how this works, you generate a signed request and send it via HTTP POST from your system. Redox validates the signature in the request, then sends back a response with the access token. You use this access token to make an API request to Redox.

Expiration for access token

Just note that the access token we provide to you expires after 5 minutes. You can use this access token to make any API requests within 5 minutes, but if a request fails, it's likely that your access token has expired. You must send a new authentication request to generate a new access token.

If you have high traffic and don't want to disrupt your workflow, you can use a service to refresh your access token every 5 minutes.

If you have low traffic, you can run an authentication request prior to making any API request.

  1. Generate and sign a JWT with the following header values:
    ParameterRequiredDescription
    algYThe JWA algorithm used for signing the authentication JWT. Note that we currently only support RS384.
    kidYThe identifier of the key-pair used to sign this JWT. This identifier tells us which public key to use to verify the JWT.
    typYThis is the type of token request. Populate this with JWT.
    jkuNThis field may be populated if you provided a JWKS URL in the Dashboard. If you provide it here, the URL should match what's saved in the Dashboard. Populate this with the TLS-protected JWKS URL, which contains the public key(s) that are accessible without authentication or authorization. If this field isn't present, Redox reverts to what's saved in the Dashboard.
  2. Populate the body of the JWT with the following claims:
    ParameterRequiredDescription
    issYThe issuer of the JWT. This should be populated with the client_id of the key you created in the Dashboard. Keep in mind that this is the same value that's provided for the sub claim.
    subYThis should be populated with the client_id of the key you created in the Dashboard. Keep in mind that this is the same value that's provided for the iss claim.
    audYThe audience of the JWT. This should be populated with https://api.redoxengine.com/v2/auth/token.
    iatYThe UTC timestamp for when the JWT was created (e.g.,1970-01-01T00:00:00Z UTC). This time must not be greater than 5 before exp below.
    expYThe expiration UTC timestamp for the JWT (e.g., 1970-01-01T00:00:00Z UTC). This time must not be greater than 5 minutes in the future.
    jtiYThis is a nonce string value that uniquely identifies this JWT. Redox denies requests if the jti is reused within the lifetime of the JWT.
    View an example of a valid JWT.
  3. Send the authentication request to https://api.redoxengine.com/v2/auth/token. If you're using Postman, send the authentication request via HTTP POST. For the header, use content-type application/x-www-form-urlencoded. Then populate the request with the following parameters:
    ParameterRequiredDescription
    grant_typeYPopulate this with client_credentials.
    client_assertion_typeYPopulate this with urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
    client_assertionYPopulate this with the signed authentication JWT value, which you generated in the previous steps.
    If you're using your own application, see some examples below.
  4. If your request is populated correctly and Redox successfully validates your signature, Redox responds with an access token.

Initiate requests

You can now initiate requests with the access token in the Authorization HTTP header using the Bearer authentication scheme.