Heidi API
Authentication

Authentication

Authentication Flow

  1. To authenticate with the Heidi API and use the widget, you will need to generate a JSON Web Token (JWT) using your API key.

  2. The API key provided is unique to your EHR system.

  3. Heidi will use your API key in combination with your EHR User UID and email address to generate a unique "Heidi API User" account for the EHR User making the request.

Authenticate with the API

Method: GET

Path: /jwt

Description: Get a JWT token for authenticating with the API.

Request

GET /jwt?email=test@heidihealth.com&third_party_internal_id=123
Heidi-Api-Key: <heidi_api_key>

Response

{
  "token": "JWT_TOKEN",
  "expiration_time": "2024-08-01T00:00:00.000Z"
}

Link to a Heidi Account

Method: POST

Path: /users/linked-account

Description: Linked an API user to a Heidi account.

Request

POST /users/linked-account
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "kinde_user_id": "kp_xxx",
}

Response

{
  "account": {
    "_id": "690d2e568252d4ba7136bcf5",
    "user_id": "kp_c2487b8e79e3413e8cd590ec43d41c9a",
    "ehr_provider": "Heidi",
    "ehr_email": "test@heidi.com",
    "ehr_user_id": "123",
    "deleted_at": null,
    "created_at": "2025-11-06T23:25:10.127632",
    "updated_at": "2025-11-06T23:25:10.127634"
  }
}

If a user is already linked to a Heidi account, the following error will be returned:

{
  "detail": {
    "msg": "Heidi account with user_id kp_xxx already linked to an OpenAPI User",
    "type": "OpenAPIHeidiAccountAlreadyLinkedError"
  }
}

Unlink a Heidi Account

Method: DELETE

Path: /users/linked-account:unlink

Description: Remove a linked Heidi account from an API user.

Request

DELETE /users/linked-account:unlink
Authorization: Bearer <your_token>

Response

{
  "is_success": true
}

Checking link status

Method: GET

Path: /users/linked-account/access

Description: Check if an API user is linked to a Heidi account.

Request

GET /users/linked-account/access
Authorization: Bearer <your_token>

Response

{
  "is_valid": true,
  "is_linked": true,
  "account": {
    "user_id": "Heidi User ID",
    "ehr_provider": "Your EHR Provider",
    "ehr_email": "The email provided with the API key",
    "ehr_user_id": "The user ID provided with the API key"
  },
  "heidi_email": "The users' email",
  "linked_account_plan": "The users' Heidi plan"
}

In the response above, if is_linked is false, the user is not linked to a Heidi account. If is_linked is true, the user is linked to a Heidi account.

OverviewTemplates