Manage My API Keys - hmislk/hmis GitHub Wiki

Manage My API Keys

API keys allow external systems and integrations to authenticate with the HMIS REST API without using a username and password. Each key is tied to your user account and has an expiry date.

Navigation

Main Menu → ⚙ (Cogwheel icon, top right) → Manage My API Keys

The Page

The page has two sections side by side:

  • Left — Add New API Key: Create a new key by selecting a type, entering a value, and setting an expiry date.
  • Right — My Active API Keys: Lists all your active, non-expired keys with a Remove button for each.

Adding a Key

  1. Navigate to ⚙ → Manage My API Keys.

  2. In the Key Name dropdown, select the key type that matches the API you want to use:

    Key Type Used For
    Finance Finance and billing endpoints (Finance header)
    Clinical Clinical endpoints (Clinical header)
    FHIR FHIR R5 Patient API (FHIR header)
    Config Configuration endpoints
    General General purpose endpoints
    Admin Administration endpoints
    Token Generic token-based access

  3. In the Key Value field, enter a unique string. A UUID is pre-filled — you can keep it or replace it. You can generate one at any UUID generator, or use the pre-filled value.

  4. Set a Date of Expiry. Keys stop working after this date.

  5. Click Add Key.

The new key appears immediately in the My Active API Keys table on the right.

Removing a Key

Click Remove next to any key in the My Active API Keys table to revoke it immediately.

Using a Key

Pass the key value in the appropriate HTTP request header for the API you are calling.

Example — FHIR Patient API:

curl -H "FHIR: your-key-value" \
     http://your-server/rh/api/fhir/Patient/12345

Example — Finance API:

curl -H "Finance: your-key-value" \
     http://your-server/rh/api/fhir/cash_invoice/HQ/1

Security Notes

  • Keep key values confidential — treat them like passwords.
  • Set expiry dates no longer than necessary.
  • Remove keys that are no longer in use.
  • Keys are validated against your user account; if your account is retired or deactivated, all your keys stop working immediately.

Related

Back