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.
Save Your API Secret

This is the only time you can view this API secret. Store it securely immediately. If lost, it cannot be recovered, and you will need to generate a new key pair.

Generate a JWT Token​

A JWT token is obtained by calling the /v1/auth/token endpoint with your 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"
}

A successful response body will contain a token property, which is the JWT token you'll need to use for subsequent API calls. The token is valid for 24 hours.

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>

Troubleshooting 401 Authorization Errors​

A 401 Unauthorized response typically means your token is invalid. Double-check that:

  • The Authorization header is present.
  • The header value is formatted as Bearer <token>.
  • The token is complete and not cut off.
  • The token hasn't expired (24-hour limit).