Authentication

Get Authenticated to the HIE

The HIE API uses a two-step authentication process to ensure secure access to healthcare data. First, you'll use Basic Authentication to obtain a JWT token, then use that token for subsequent API requests.

Authentication

The HIE API uses a two-step authentication process to ensure secure access to healthcare data. First, you'll use Basic Authentication to obtain a JWT token, then use that token for subsequent API requests.

Authentication Flow

1. Using Basic Authentication to Obtain a Token

Use your username and password to make a request to the token endpoint. These credentials are provided when you register for API access.

{{base_url}}/v1/hie-auth?key={{your-key-here}}

2. Token Retrieval

The API when accessed successfully returns a JWT token in the response. This token is valid for a single API call/session.

3. Authenticating API Requests with the JWT Token

Include the JWT token in the Authorization header of all subsequent API requests using the Bearer authentication scheme.

Step 1: Obtaining Basic Authentication

Before you can request a JWT token, you need to set up Basic Authentication using your HIE account credentials. You'll need to register for an account in the HIE Developer Portal to receive your API username and password.

Finding Your API Credentials:

Authentication Methods

Basic Authentication

With Basic Authentication, you'll use these credentials to request a token through our provided API. We generate and manage the tokens for you.

1. Agent ID Your unique identifier in the HIE ecosystem. This serves as your API's digital number within the HIE network and will be used when generating the token to authenticate API calls.
2. Username Your account identifier used for Basic Authentication headers when accessing the HIE API. This is used to request a token from our API.
3. Password Your account's secret access key. This must be encoded with your username for secure API requests to obtain a token.

Token Authentication

Token Authentication allows you to generate your own JWT tokens for your applications. You control the token creation process and can implement custom token management within your systems.

4. Consumer Key This is your application's public identifier in the HIE ecosystem. It is key to generating your own JWT token for authenticating API calls.
5. Secret Your private authentication key that works like a password for your application. This is used along with the Agent ID and Consumer Key to generate JWT tokens that will authenticate your API calls.

To access your API credentials, log in to the HIE Developer Portal and navigate to the Credentials menu. Select your issued UAT credentials and click "View". Scroll down to the API Credentials section, where your credentials will be displayed.

Note: Keep your API credentials secure and never share them publicly. If you believe your credentials have been compromised, you should regenerate them immediately from the AfyaLink Portal.

Step 2: Obtaining a JWT Token

Once you have your Basic Authentication credentials, you can obtain a JWT token using the HIE API. Make a request to the token endpoint using your Basic Authentication credentials.

Snippets

cURL

curl -X GET "{base_url}/v1/hie-auth?key=YOUR-CONSUMER-KEY" \
  -H "Authorization: Basic $(echo -n 'YOUR-USERNAME:YOUR-PASSWORD' | base64)

Python

import requests
import base64

# Credentials
username = "YOUR-USERNAME"
password = "YOUR-PASSWORD"
consumer_key = "YOUR-CONSUMER-KEY"

# Create Basic Auth header
credentials = f"{username}:{password}"
basic_auth = base64.b64encode(credentials.encode()).decode()

# Make the request
response = requests.get(
    f"{base_url}/v1/hie-auth?key={consumer_key}",
    headers={"Authorization": f"Basic {basic_auth}"}
)

# Get the JWT token
token = response.json()["token"]

Javascript

const base64 = require("base-64");

const username = "YOUR-USERNAME";
const password = "YOUR-PASSWORD";
const consumerKey = "YOUR-CONSUMER-KEY";
const baseUrl = "YOUR-BASE-URL";

const credentials = `${username}:${password}`;
const basicAuth = base64.encode(credentials);

async function getToken() {
  try {
    const response = await fetch(`${baseUrl}/v1/hie-auth?key=${consumerKey}`, {
      method: "GET",
      headers: {
        "Authorization": `Basic ${basicAuth}`,
        "Content-Type": "application/json",
      },
    });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    console.log("JWT Token:", data.token);
    return data.token;
  } catch (error) {
    console.error("Error fetching token:", error);
  }
}

getToken();

Error Responses

If authentication fails, the API will return one of the following error responses:

Status Code	Error Message	Description
401	Unauthorized	Invalid credentials provided for Basic Authentication
401	Invalid token	The JWT token is invalid or has expired
403	Forbidden	The provided credentials do not have permission to access the requested resource