Healthcheck Tenant Admin Connector

The Healthcheck Tenant Admin Connector provides access to account, authentication, and administrative workflows for Tenant Admin users within a configured tenant.

It is built on top of the shared Healthcheck HTTP layer and maintains its own Tenant Admin authentication context through HCTenantAdminClient.

Features

1. Tenant Admin login and token refresh
2. Authenticated registration of new Tenant Admin accounts
3. Tenant Admin email verification
4. Password reset and password reset confirmation
5. Tenant Admin header and dashboard retrieval
6. User status update
7. Shared Healthcheck HttpClient support

Installation

npm install @healthcloudai/hc-tenant-admin-connector \
@healthcloudai/hc-http

Import

import { HCTenantAdminClient } from "@healthcloudai/hc-tenant-admin-connector";
import { FetchClient } from "@healthcloudai/hc-http";

Setup

Create the shared HTTP client, initialize HCTenantAdminClient, and configure the tenant context and environment before making requests.

const httpClient = new FetchClient();
const tenantAdminClient = new HCTenantAdminClient(httpClient);

tenantAdminClient.configure("example-tenant", "dev");

The configured tenant ID is added internally when the client builds API requests. Public SDK methods do not require a { Data: ... } request wrapper or a separate TenantID argument.

API Key

Use setApiKey(...) to attach an API key header to requests from HCTenantAdminClient.

const apiKey = process.env.HEALTHCLOUD_API_KEY;

if (!apiKey) {
  throw new Error("HEALTHCLOUD_API_KEY is required.");
}

tenantAdminClient.setApiKey("x-api-key", apiKey);

Authentication and response contract

loginTenantAdmin(...) starts the Tenant Admin authenticated session. After a successful login response, the client stores the returned authentication tokens internally for protected Tenant Admin requests.

Protected methods, including registration, Tenant Admin information retrieval, dashboard retrieval, and user deactivation, use the stored authentication context automatically. Call loginTenantAdmin(...) successfully on the same client instance before using these methods.

Login, email verification, and password recovery methods receive the configured tenant context automatically, but do not require the consumer to provide authentication headers or backend request envelopes manually.

All methods return the backend response envelope without unwrapping its Data value:

interface APIResponse<T> {
  Data: T;
  IsOK: boolean;
  ErrorMessage: string | null;
}

Methods

Login Tenant Admin

Authenticates a Tenant Admin account within the configured tenant context.

The client builds the API request internally, includes the configured tenant ID, stores authentication tokens from a successful response, and returns the complete backend response envelope.

Method signature

tenantAdminClient.loginTenantAdmin(
  email: string,
  password: string
): Promise<APIResponse<IdentityAuthorization>>

Usage example

const response = await tenantAdminClient.loginTenantAdmin(
  "[email protected]",
  "ExamplePassword123!"
);

Parameters

| Parameter | Type | Required | Description | |---|---|---:|---| | email | string | Yes | Email address of the Tenant Admin account. | | password | string | Yes | Password of the Tenant Admin account. |

Returns

Promise<APIResponse<IdentityAuthorization>>

The original API response is returned to the consumer. Authentication tokens from a successful response are also stored internally by HCTenantAdminClient for subsequent authenticated requests.

API request

{
  "Data": {
    "Email": "[email protected]",
    "Password": "ExamplePassword123!",
    "TenantID": "example-tenant"
  }
}

API response

{
  "Data": {
    "AccessToken": "example-access-token",
    "RefreshToken": "example-refresh-token",
    "IDToken": "example-id-token",
    "Expiration": "2026-01-01T12:00:00.000Z"
  },
  "ErrorMessage": null,
  "IsOK": true
}

Refresh Token

Refreshes the Tenant Admin authentication session using the refresh token stored by the client after login.

This method does not require consumer-side arguments. It must be called on a client instance that already contains authentication tokens from a successful Tenant Admin login.

Method signature

tenantAdminClient.refreshToken(): Promise<APIResponse<IdentityAuthorization>>

Usage example

const response = await tenantAdminClient.refreshToken();

Returns

Promise<APIResponse<IdentityAuthorization>>

The original API response is returned to the consumer. Authentication tokens from a successful refresh response replace the tokens stored internally by the client.

API request

{
  "Data": {
    "RefreshToken": "example-refresh-token",
    "TenantID": "example-tenant"
  }
}

API response

{
  "Data": {
    "AccessToken": "example-new-access-token",
    "RefreshToken": "example-new-refresh-token",
    "IDToken": "example-new-id-token",
    "Expiration": "2026-01-01T13:00:00.000Z"
  },
  "ErrorMessage": null,
  "IsOK": true
}

Register Tenant Admin

Registers a new Tenant Admin account within the tenant configured on the client.

This is an authenticated administrative operation. Before calling registerTenantAdmin(...), the current client instance must contain a valid authenticated Tenant Admin session. The client sends the stored authentication context and adds the configured tenant ID when constructing the API request.

Method signature

tenantAdminClient.registerTenantAdmin(
  registration: RegistrationData
): Promise<APIResponse<string>>

Usage example

const response =
  await tenantAdminClient.registerTenantAdmin({
    Credentials: {
      Email: "[email protected]",
      Password: ""
    },
    User: {
      FirstName: "Alex",
      LastName: "Admin",
      Email: "[email protected]",
      Phone: "+10000000000",
      BirthDate: "1990-01-01T00:00:00Z",
      Gender: "Male"
    }
  });

Parameters

| Parameter | Type | Required | Description | |---|---|---:|---| | registration | RegistrationData | Yes | Account and profile data for the Tenant Admin being registered. | | registration.Credentials | TenantAdminCredentials | Yes | Credentials for the new Tenant Admin account. | | registration.Credentials.Email | string | Yes | Email address for the new Tenant Admin account. | | registration.Credentials.Password | string | Yes | Password value included in the registration request. | | registration.User | TenantAdminUser | Yes | Profile data for the new Tenant Admin account. | | registration.User.FirstName | string | Yes | First name of the new Tenant Admin. | | registration.User.LastName | string | Yes | Last name of the new Tenant Admin. | | registration.User.Email | string | Yes | Email stored in the Tenant Admin profile. | | registration.User.Phone | string | No | Phone number for the Tenant Admin profile. | | registration.User.BirthDate | string | No | Birth date in ISO 8601 format. | | registration.User.Gender | string | No | Gender value for the Tenant Admin profile. |

TenantID is not passed in the public method call. The client adds the tenant ID from its existing configuration when constructing the API request.

Returns

Promise<APIResponse<string>>

Returns the complete backend response envelope from the registration operation.

API request

{
  "Data": {
    "TenantID": "example-tenant",
    "Credentials": {
      "Email": "[email protected]",
      "Password": ""
    },
    "User": {
      "FirstName": "Alex",
      "LastName": "Admin",
      "Email": "[email protected]",
      "Phone": "+10000000000",
      "BirthDate": "1990-01-01T00:00:00Z",
      "Gender": "Male"
    }
  }
}

API response

{
  "Data": "invite-code",
  "ErrorMessage": null,
  "IsOK": true
}

Verify Tenant Admin Email

Verifies the email address associated with a Tenant Admin registration flow.

The client builds the verification request internally and automatically includes the configured tenant ID.

Method signature

tenantAdminClient.verifyTenantEmail(
  email: string,
  code: string,
  language?: string
): Promise<APIResponse<string>>

Usage example

const response = await tenantAdminClient.verifyTenantEmail(
  "[email protected]",
  "123456",
  "en"
);

Parameters

| Parameter | Type | Required | Description | |---|---|---:|---| | email | string | Yes | Email address of the Tenant Admin account being verified. | | code | string | Yes | Verification code received by email. | | language | string | No | Language used for the verification request. Defaults to "en". |

Returns

Promise<APIResponse<string>>

Returns the complete backend response envelope from the email verification operation.

API request

{
  "Data": {
    "Step": "EMAIL_VERIFY",
    "User": {
      "Email": "[email protected]",
      "TenantID": "example-tenant"
    },
    "Data": "123456",
    "Language": "en"
  }
}

API response

{
  "Data": null,
  "ErrorMessage": null,
  "IsOK": true
}

Reset Password

Starts a Tenant Admin password reset flow.

The client adds the configured tenant ID when constructing the API request. Set isPasswordResetWithOTP to true when the reset flow should use OTP confirmation.

Method signature

tenantAdminClient.resetPassword(
  email: string,
  isPasswordResetWithOTP?: boolean
): Promise<APIResponse<boolean>>

Usage example

const response = await tenantAdminClient.resetPassword(
  "[email protected]"
);

Parameters

| Parameter | Type | Required | Description | |---|---|---:|---| | email | string | Yes | Email address of the Tenant Admin account. | | isPasswordResetWithOTP | boolean | No | Set to true to start an OTP-based reset flow. Defaults to false. |

Returns

Promise<APIResponse<boolean>>

API request

{
  "Data": {
    "Email": "[email protected]",
    "TenantID": "example-tenant"
  }
}

API response

{
  "Data": true,
  "ErrorMessage": null,
  "IsOK": true
}

OTP usage example

const response = await tenantAdminClient.resetPassword(
  "[email protected]",
  true
);

OTP API request

{
  "Data": {
    "Email": "[email protected]",
    "TenantID": "example-tenant",
    "IsPasswordResetWithOTP": true
  }
}

OTP API response

{
  "Data": true,
  "ErrorMessage": null,
  "IsOK": true
}

Confirm Reset Password

Completes a Tenant Admin password reset flow.

resetPasswordConfirm(...) accepts confirmation data directly. The client wraps this data in the backend request envelope and automatically adds the configured tenant ID.

The method supports both OTP-based and link-based confirmation flows:

• When IsPasswordResetWithOTP is true, Code is required.
• When IsPasswordResetWithOTP is not true, Token is required.

Method signature

tenantAdminClient.resetPasswordConfirm(
  confirmation: ResetPasswordConfirmation
): Promise<APIResponse<boolean>>

OTP-based password reset confirmation

Use this flow when password reset was started with OTP enabled.

Usage example

const response =
  await tenantAdminClient.resetPasswordConfirm({
    Email: "[email protected]",
    Password: "NewExamplePassword123!",
    IsPasswordResetWithOTP: true,
    Code: "123456"
  });

Parameters

| Parameter | Type | Required | Description | |---|---|---:|---| | Email | string | Yes | Email address of the Tenant Admin account. | | Password | string | Yes | New password for the account. | | IsPasswordResetWithOTP | true | Yes | Selects the OTP-based confirmation flow. | | Code | string | Yes | OTP code received by the user. | | Token | string | No | Optional token value when supported by the flow. |

Returns

Promise<APIResponse<boolean>>

API request

{
  "Data": {
    "Email": "[email protected]",
    "Password": "NewExamplePassword123!",
    "IsPasswordResetWithOTP": true,
    "Code": "123456",
    "TenantID": "example-tenant"
  }
}

API response

{
  "Data": true,
  "ErrorMessage": null,
  "IsOK": true
}

Link-based password reset confirmation

Use this flow when password reset was started from an email link.

The frontend is responsible for extracting the token from the password reset link and passing it directly to resetPasswordConfirm(...). The client adds the configured tenant ID internally.

Usage example

const response =
  await tenantAdminClient.resetPasswordConfirm({
    Email: "[email protected]",
    Password: "NewExamplePassword123!",
    Token: "example-reset-token"
  });

Parameters

| Parameter | Type | Required | Description | |---|---|---:|---| | Email | string | Yes | Email address of the Tenant Admin account. | | Password | string | Yes | New password for the account. | | Token | string | Yes | Reset token extracted from the email link. | | IsPasswordResetWithOTP | false | No | May be supplied as false for the link-based flow. | | Code | string | No | Optional code value when supported by the flow. |

Returns

Promise<APIResponse<boolean>>

API request

{
  "Data": {
    "Email": "[email protected]",
    "Password": "NewExamplePassword123!",
    "Token": "example-reset-token",
    "TenantID": "example-tenant"
  }
}

API response

{
  "Data": true,
  "ErrorMessage": null,
  "IsOK": true
}

Get Tenant Admin Info

Retrieves header information for the currently authenticated Tenant Admin.

This is an authenticated method. The client automatically sends the stored authentication token and configured tenant context.

Method signature

tenantAdminClient.getTenantAdminInfo(): Promise<APIResponse<TenantAdminDashboard>>

Usage example

const response = await tenantAdminClient.getTenantAdminInfo();

Returns

Promise<APIResponse<TenantAdminDashboard>>

API request

GET /api/admin/tenant/header
Authorization: Bearer example-id-token
X-Tenant-ID: example-tenant

API response

{
  "Data": {
    "Record": {
      "Status": 1,
      "FirstName": "Alex",
      "LastName": "Admin",
      "MiddleName": null,
      "BirthDate": "1990-01-01T00:00:00Z",
      "Email": "[email protected]",
      "Phone": "+10000000000",
      "Gender": "Male",
      "Race": null,
      "Ethnicity": null,
      "CRMID": null,
      "AppleUserId": null,
      "Address": null,
      "Attributes": null,
      "CompositeID": "example-tenant/[email protected]",
      "FHIRID": null,
      "AthenaID": null,
      "Created": "2026-01-01T00:00:00Z",
      "Modified": "2026-01-01T00:00:00Z",
      "CreatedByID": null,
      "ModifiedByID": null,
      "IsDeactivated": false,
      "TenantID": "example-tenant",
      "ID": "example-user-id"
    }
  },
  "ErrorMessage": null,
  "IsOK": true
}

Get Tenant Admin Dashboard

Retrieves dashboard data for the currently authenticated Tenant Admin.

This is an authenticated method. The client automatically sends the stored authentication token and configured tenant context.

Method signature

tenantAdminClient.getTenantAdminDashboard(): Promise<APIResponse<TenantAdminDashboard>>

Usage example

const response = await tenantAdminClient.getTenantAdminDashboard();

Returns

Promise<APIResponse<TenantAdminDashboard>>

API request

GET /api/tenant/dashboard
Authorization: Bearer example-id-token
X-Tenant-ID: example-tenant

API response

{
  "Data": {
    "Record": {
      "Status": 1,
      "FirstName": "Alex",
      "LastName": "Admin",
      "Email": "[email protected]",
      "TenantID": "example-tenant",
      "IsDeactivated": false,
      "ID": "example-user-id"
    }
  },
  "ErrorMessage": null,
  "IsOK": true
}

Deactivate User

Deactivates a user within the configured tenant context.

This is an authenticated method. The client sends the stored authentication token and automatically adds the configured tenant ID to the API request.

Method signature

tenantAdminClient.deactivateUser(
  email: string
): Promise<APIResponse<boolean>>

Usage example

const response = await tenantAdminClient.deactivateUser(
  "[email protected]"
);

Parameters

| Parameter | Type | Required | Description | |---|---|---:|---| | email | string | Yes | Email address of the user to deactivate. |

Returns

Promise<APIResponse<boolean>>

API request

{
  "Data": {
    "Email": "[email protected]",
    "TenantID": "example-tenant"
  }
}

API response

{
  "Data": true,
  "ErrorMessage": null,
  "IsOK": true
}

Response handling

The connector returns the backend APIResponse<T> envelope for each method. It does not expose only Data in place of the original response.

const response = await tenantAdminClient.getTenantAdminDashboard();

if (!response.IsOK) {
  console.error(response.ErrorMessage);
  return;
}

console.log(response.Data);

Configuration and local authentication-state checks may fail before a request is sent.

const tenantAdminClient = new HCTenantAdminClient(httpClient);

await tenantAdminClient.loginTenantAdmin(
  "[email protected]",
  "ExamplePassword123!"
);
// Throws: HCTenantAdminClient is not configured. Call configure() first.

Protected methods require authentication tokens to already be stored in the same client instance.

const tenantAdminClient = new HCTenantAdminClient(httpClient);

tenantAdminClient.configure("example-tenant", "dev");

await tenantAdminClient.getTenantAdminDashboard();
// Throws: No ID token available