Authenticate a legacy API key

Last updated: Feb 26, 2024

This article is for legacy users since API keys have been deprecated. Learn how to use OAuth keys, which are our preferred authentication method.

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

  1. Log in to the Redox dashboard.
  2. From the navigation menu, click 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 section below contains legacy keys. To create a legacy 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 6.
  5. A modal opens with API key details. In the Name field, enter the API key name. If you're a new user, you won't be able to create a legacy key.
  6. If you're an existing user with legacy keys, radio buttons display for Legacy and OAuth options. Select the Legacy radio button.
  7. Click the Add button.
  8. The Settings page displays. Copy the API key value and generate a new secret value to send a request for an access token.
  9. Use the following request:
    Example: Request for generating an access token
    bash
    1
    curl -X POST https://api.redoxengine.com/auth/authenticate \
    2
     -H 'Content-Type: application/json' \
    3
     -d '{"apiKey": "not-a-real-api-key", "secret": "super-secret-client-secret"}'
    Example: Response for generating an access token
    json
    1
    {
    2
    "accessToken": "13d5faa8-aacd-4a0d-a666-51455b1b2ced",
    3
    "expires": "2015-03-25T20:52:35.000Z",
    4
    "refreshToken": "4ed7b234-9bde-4a9c-9c86-e1bc6e535321"
    5
    }
    Use the accessToken (in the first line of the response) to authenticate in later steps.  Take note of the expires value, which contains the exact date and time that your access token expires. Access tokens expire 24 hours after retrieval.  Then use the refreshToken to retrieve a new access token after this one expires. See the details for refreshing your token further down below.
  10. Authenticate your request. The Data Model API relies on Oauth 2.0 Bearer to authenticate requests. All requests via the Data Model API must contain an Authorization header with a valid access token in the following format: Authorization: Bearer [your-accessToken]
    Example: Authorization header for a request
    bash
    1
    curl -X POST https://api.redoxengine.com/endpoint \
    2
     -H '{"Authorization": "Bearer f81eeac9-7cb0-4a82-951b-724f592723ae"}'

Making a request

After successfully authenticating, you can initiate requests to any endpoints you have verified. If you want to send test requests, you can send them to https://api.redoxengine.com/endpoint.

Every Data Model API request must contain these headers and body parameters.

Header
Value
Description
Authentication
Bearers `your-authToken`
The token that authenticates your request. This header is required.
Content-Type
application/json
The value that identifies the type of API call.
Parameter
Type
Description
Meta.DataModel
String
The data model corresponding to the type of data you're sending or requesting.
Meta.EventType
String
The event type of the data model that you're sending or requesting. Learn more about event types.
Meta.Source.ID
String
The identifier for the source sending the outgoing request. This parameter is required if you have more than one legacy API key. Learn more about identifying a source.
Meta.Destinations[].ID
String array
Objects with ID value(s) of the endpoint(s) you're sending data to or the endpoint you're requesting data from.

A request should generally look like this:

Example: General request
bash
1
curl \
2
 -X POST https://api.redoxengine.com/endpoint \
3
 -H "Content-Type: application/json" \
4
 -H "Authorization: Bearer[access-token-here]" \
5
 -d '{
6
   "Meta": {
7
     "DataModel": "PatientAdmin",
8
     "EventType": "Arrival",
9
     "Destinations": [
10
       {
11
         "ID": "af394f14-b34a-464f-8d24-895f370af4c9",
12
         "Name": "Redox EMR"
13
       }
14
     ]
15
   },
16
   "Patient": {
17
      # … payload omitted
18
   }
19
 }'

Refreshing your access token

You can use the refresh token returned from the most recent authentication request to retrieve a new access token via the refresh token endpoint:

Example: Request for refreshing an access token
bash
1
curl -X POST https://api.redoxengine.com/auth/refreshToken \
2
 -H '{"Content-Type": "application/json"}' \
3
 -d '{"apiKey": "not-a-real-api-key", "refreshToken": "4ed7b234-9bde-4a9c-9c86-e1bc6e535321"}'

The object returned for a successful response is the same as that for the original access token retrieval request noted above.

Generating a new secret value

If either your API key or secret value are exposed, you must generate a new secret value. Learn how to generate a new secret value.