Skip to main content

Authentication

All requests to HealthEx APIs must be authenticated. Here's how it works, at a high level:

  • Create an API key and secret in the HealthEx web application
  • Call the /v1/auth/token API with your API key and secret to generate a JWT token.
  • Include this JWT token as a header in all subsequent requests.

The rest of this document will walk you through the process in detail.

Creating an API key and secret​

In order to create an API key and secret, you will need to have a HealthEx account with administrator privileges.

To create an API key:

  1. Log in to your HealthEx account and navigate to the "Admin" tab in the top navigation bar.
  2. Choose the "Manage API Keys" tab.
  3. Click "Create New" to create a new API key.
  4. Give your API key a descriptive name to help you identify it. You may assign additional permissions to the API key. However, none of the currently supported HealthEx APIs require any additional permissions.
  5. Click "Create API Key"
  6. Your new API key and secret will now be displayed. Please note that this is the only time you will be able to see the API secret, so you must record in a safe place somewhere. If you lose the secret, you will need to create an entirely new API key/secret pair!

Generate a JWT Token​

A JWT token is obtained by calling the /v1/auth/token API with API key and secret.

POST https://api.healthex.io/v1/auth/token
Content-Type: application/json
Accept: application/json
{
  "apiKey": "Your API key",
  "apiSecret": "Your API secret"
}

Assuming your API key and secret are valid, you will receive a successful response. The response body will contain a token property, which is the JWT token you'll need to use for subsequent API calls.

Your token will be valid for 24 hours. After that period, you'll need to call this API again to generate a new token.

For more details, see the generateToken API reference.

Using the JWT Token in API calls​

The JWT token should be included in the Authorization header of subsequent requests to the HealthEx API, using the Bearer scheme.

Authorization: Bearer <JWT Token>

If you receive a 401 Unauthorized response to any API call, this may mean you forgot to include (or incorrectly included) this header. Other causes of this response can include:

  • Malformed token (for example, not including the whole token)
  • Expired token (tokens expire after 24 hours)