Authenticate a legacy API key

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 Sources tab opens and displays any configured sources and OAuth API keys. Find the source associated with the legacy API key you want to use. Click the Edit button. Or, to create a legacy API key, follow the steps to create a new source. Legacy API keys are tied 1:1 to a source, so to create a new one, you must create a new source. Then return to these instructions.
4. The Settings page displays. Copy the legacy API key value and generate a new secret value to send a request for an access token.
5. Use the following request:

   Example: Request for generating an access token

   bash

   Copy

   1
   curl -X POST https://api.redoxengine.com/auth/authenticate \
   2
    -H 'Content-Type: application/json' \
   3
    -d '{"apiKey": "{{api-token}}", "secret": "super-secret-client-secret"}'

   Example: Response for generating an access token

   json

   Copy

   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.

   401 error code

   If you attempt to use an expired access token with a request, you'll receive a 401 Unauthorized error.

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

   Copy

   1
   curl -X POST https://api.redoxengine.com/endpoint \
   2
    -H '{"Authorization": "Bearer f81eeac9-7cb0-4a82-951b-724f592723ae"}'

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

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

A request should generally look like this:

1
curl \
2
 -X POST https://api.redoxengine.com/endpoint \
3
 -H "Content-Type: application/json" \
4
 -H "Authorization: Bearer $API_TOKEN" \
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
 }'

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

1
curl -X POST https://api.redoxengine.com/auth/refreshToken \
2
 -H '{"Content-Type": "application/json"}' \
3
 -d '{"apiKey": "{{API-token}}", "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.

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.