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:

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

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

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.

Log in to the dashboard.
From the navigation menu, select the Developer page.
By default, the Developer page opens and displays the API Keys tab.
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 want to configure an existing API key, click the Edit button next to it. Then skip to step 7.
User-level API keys
If you're using the Redox Platform API, you need to create a user-level API key instead. Learn how to create and authenticate a user-level API key.
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.
Click the Add button.
Create an OAuth API key
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.

Generate keys in the Redox dashboard

Provide your public key

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.

From the Settings tab of the API key, click the DevTools (Postman) tab.
The Postman options display. Click the Download Postman collection button.
Run the authentication collection in Postman and select the option for how you want to run it: Postman for Web or Postman for Mac.
Postman opens and automatically imports the Redox Platform Authentication collection. You can use this collection for authenticating requests sent via the Redox FHIR® API or the Data Model API.
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.
In Postman, click the Environments tab.
Click the Import button.
From the file explorer, select the Postman environment that you just downloaded.
The Postman environment is added. Select the environment name in the left-hand pane or in the Environment drop-down.
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

Generate a signed request in your system using your private key.

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.

With Postman, the authentication request looks something like this:

Example: Auth request for OAuth (cURL)

1
curl --location --request POST 'https://api.redoxengine.com/v2/auth/token' \
2
--header 'Content-Type: application/x-www-form-urlencoded' \
3
--data-urlencode 'grant_type=client_credentials' \
4
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
5
--data-urlencode 'client_assertion={{signed_assertion}}'

With your own application, the request may look like this:

Example: Auth request for OAuth (JavaScript)

1
const jose = require('jose');
2
const axios = require('axios');
3
const randomBytes = require('crypto').randomBytes;
4
const qsStringify = require('querystring').stringify;
5
const https = require('node:https');
6

7
// import your private key as PEM or JWK
8
const privateKeyPEM = ``;  // INSERT PRIVATE PEM KEY HERE
9

10
const clientId = '<INSERT CLIENT ID HERE>';
11
const iat = Math.floor(new Date().getTime()/1000);  // Current timestamp in seconds (undefined is valid)
12
const aud = 'https://api.redoxengine.com/v2/auth/token';
13
const kid = '<INSERT KID HERE>';
14
const scope = 'fhir:development'; // valid scopes are 'fhir:development', 'fhir:staging', or 'fhir:production'
15

16

17

18
async function getSignedAssertion(clientId, privateKeyPEM, kid, aud, iat, scope) {
19
    const privateKey = await jose.importPKCS8(privateKeyPEM, 'RS384');
20

21
    const payload = {
22
        scope,
23
    };
24

25
    const signedAssertion = await new jose.SignJWT(payload)
26
    .setProtectedHeader({
27
        alg: 'RS384',
28
        kid: kid
29
    })
30
    .setAudience(aud)
31
    .setIssuer(clientId)
32
    .setSubject(clientId)
33
    .setIssuedAt(iat)
34
    .setJti(randomBytes(8).toString('hex')) // a random string to prevent replay attacks
35
    .sign(privateKey);
36

37
    return signedAssertion;
38
}
39

40
async function requestJwtAccessTokenAxios(signedAssertion, scope) {
41
    const requestBody = qsStringify({
42
      grant_type: 'client_credentials',
43
      client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
44
      client_assertion: signedAssertion,
45
      scope
46
    });
47
  
48
    try {
49
      const result = await axios.post(
50
        "https://api.redoxengine.com/v2/auth/token", requestBody, {
51
          headers: {
52
            'content-type': 'application/x-www-form-urlencoded'
53
          }
54
        }
55
      );
56
  
57
      // return response with keys: access_token, scope, token_type, and expires_in
58
      return result.data;
59
    }
60
    catch(e) {
61
      return e.response.data;
62
    }
63
}
64

65
async function requestJwtAccessTokenNoLibrary(signedAssertion, scope) {
66

67
    const requestBody = qsStringify({
68
        grant_type: 'client_credentials',
69
        client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
70
        client_assertion: signedAssertion,
71
        scope
72
      });
73

74
    const options = {
75
        method: 'POST',
76
        headers: { 
77
            'content-type': 'application/x-www-form-urlencoded'
78
        }
79
    };
80

81
    return new Promise(function(resolve, reject) {
82
        try {
83
            const req = https.request('https://api.redoxengine.com/v2/auth/token', options, (res) => {
84
                console.log('statusCode:', res.statusCode);
85
                console.log('headers:', res.headers);
86
                let data = '';
87
                
88
                res.on('data', (d) => {
89
                    data += d;
90
                });
91
                res.on('end', (d) =>{
92
                    const parsed = JSON.parse(data);
93
                    resolve(parsed);
94
                });
95
                res.on('error', (error) => {
96
                    throw error;
97
                })
98
            });
99
        
100
            req.write(requestBody);
101
            req.end();
102
        }
103
        catch(e) {
104
            reject(e);
105
        }
106
        
107
    });
108
}
109

110
(async() => {
111
    const signedAssertion = await getSignedAssertion(clientId, privateKeyPEM, kid, aud, iat, scope);
112
    const accessTokenAxios = await requestJwtAccessTokenAxios(signedAssertion, scope);
113
    const accessTokenNoLibrary = await requestJwtAccessTokenNoLibrary(signedAssertion, scope);
114
    console.log({accessTokenAxios});
115
    console.log({accessTokenNoLibrary});
116
})();

Example: Auth request for OAuth (python)

1
import datetime
2
import jwt
3
import requests
4
from uuid import uuid4
5

6
with open('private_key.pem', 'rb') as f:
7
  private_key = f.read()
8

9
class BackendServiceAuth(requests.auth.AuthBase):
10

11
  def __init__(self, auth_location, client_id, kid, private_key):
12
    self.auth_location = auth_location
13
    self.client_id = client_id
14
    self.kid = kid
15
    self.private_key = private_key
16
    self.token = None
17

18
  def __call__(self, request):
19
    if not self.token:
20
      expiration = datetime.datetime.now() + datetime.timedelta(minutes=5)
21
      # Add 'kid' property to the header
22
      headers = {
23
        'kid': self.kid,
24
        'alg': 'RS384',
25
        'typ': 'JWT',
26
      }
27

28
      assertion = jwt.encode(
29
        {
30
          'iss': self.client_id,
31
          'sub': self.client_id,
32
          'aud': self.auth_location,
33
          'exp': int(expiration.strftime('%s')),
34
          'iat': int(datetime.datetime.now().strftime('%s')),
35
          'jti': uuid4().hex,
36
        },
37
        self.private_key,
38
        algorithm='RS384',
39
        headers=headers)
40

41
      print(f"assertion: {assertion}")
42

43
      payload = {
44
        'grant_type': 'client_credentials',
45
        'client_assertion_type':
46
        'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
47
        'client_assertion': assertion
48
      }
49
      try:
50
        response = requests.post(self.auth_location, data=payload, timeout=30)
51
        response.raise_for_status()
52
        self.token = response.json()['access_token']
53
        print(f"success! {response.json()}")
54
      except requests.exceptions.RequestException as e:
55
        if hasattr(e, 'response') and e.response is not None:
56
          print(f"Request failed with status code: {e.response.status_code}")
57
          print(f"Response body: {e.response.text}")
58
        else:
59
          print(f"Request failed: {e}")
60

61
    request.headers['Authorization'] = 'Bearer %s' % self.token
62
    return request
63

64
def main():
65
  client_id = '<your client id>'
66
  kid = '<the key id (kid) for your private key>'
67
  auth_location = 'https://api.redoxengine.com/v2/auth/token'
68
  auth = BackendServiceAuth(auth_location, client_id, kid, private_key)
69

70
  # Now you can use 'auth' as the authentication mechanism for your requests.
71
  response = requests.post(
72
    'https://api.redoxengine.com/fhir/R4/redox-fhir-sandbox/Development/Patient/_search',
73
    auth=auth)
74
  print(response.json())  # Example usage of the token to fetch patient data.
75

76
if __name__ == "__main__":
77
  main()

Copy the code example above and make sure the axios and jose libraries are installed with npm i axios jose. Then, update the privateKeyPEM, clientId, and kid based on the signed request you generated in step 1.

Redox validates the signature in the request using your public key, then sends back a response with the access token.
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.

JWT header and body 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.

Header values

Parameter	Required	Description
alg	Y	The JWA algorithm used for signing the authentication JWT. Note that we currently only support RS384.
kid	Y	The identifier of the key-pair used to sign this JWT. This identifier tells us which public key to use to verify the JWT.
typ	Y	The type of token request. Populate this with JWT.
jku	N	This field may be populated if you provided a JWKS URL in the Redox 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.

Body values

Parameter	Required	Description
iss	Y	The issuer of the JWT. Populate this with the client_id of the key you created in the dashboard. The iss and sub contain the same values.
sub	Y	Populate this with the client_id of the key you created in the dashboard. The iss and sub contain the same values.
aud	Y	The audience of the JWT. Populate this with https://api.redoxengine.com/v2/auth/token.
iat	Y	The 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.
exp	Y	The 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.
jti	Y	A nonce string value that uniquely identifies the JWT. Redox denies requests if you attempt to reuse the jti within the lifetime of the JWT.

HTTP request body definitions

Auth request parameters

Parameter	Required	Description
grant_type	Y	Populate this with client_credentials.
client_assertion_type	Y	If using the Postman collection, this value automatically populates. If using your own application, populate this with urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion	Y	If using the Postman collection, this value automatically populates. If using your own application, populate this with the signed assertion you generated with your private key.

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:

Example: Initiating requests

1
curl \
2
-X POST https://api.redoxengine.com/endpoint \
3
-H "Content-Type: application/json" \
4
-H "Authorization: Bearer [TOKEN]" \
5
-d '{}'

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