Building an App

Marketplace apps are embedded experiences that run inside the Hint UI. You host the app, own the UI and APIs, and Hint handles:

secure authentication and session handoff
surfacing your app inside Hint at specific entry points
passing user, practice, and patient context into your app
navigation patterns via the JS SDK

Foundation: build an integration

At their foundation, all apps require an integration. The first step in building an App is Building an Integration.

Quickstart: build a minimal app

This tutorial gets you to a working embedded app that:

accepts the Marketplace handshake from Hint and returns a session_key
renders a page inside an iframe
loads the JS SDK and shows practice/user/patient context

Prerequisites

You can activate your integration for a practice (see Integration Activation).
You can host two URLs:
- a handshake URL (server endpoint)
- an iframe URL (web page)

Step 1: Handle the Marketplace handshake (server)

Create a handshake endpoint. Hint will POST a signed payload to your handshake URL with the user, practice, integration, and a short-lived access token for making Hint API requests as that user session.

Verify X-Hint-Signature exactly as described in Webhooks Security.
Create a session_key (your session identifier) and persist any session state you need.
Return session_key. Hint will append it when loading your iframe URL.

Example payload:

{
  "timestamp": "2025-10-30T14:20:19.316986-03:00",
  "user": {
    "id": "user-BtAH8TTXCo6P",
    "email": "[email protected]",
    "first_name": "Dev",
    "last_name": "User",
    "name": "Dev User",
    "partner_roles": ["admin"]
  },
  "practice": {
    "id": "pra-cmVPOcw7hcIs",
    "name": "Example Practice"
  },
  "integration": {
    "id": "int-MicbNQhj6hsv"
  },
  "access_token": "practice-scoped-access-token"
}

Example Express endpoint:

app.post("/handshake", (req, res) => {
  const signature = req.header("X-Hint-Signature");
  verifyHintSignature({ signature, body: req.body }); // reuse your webhook verifier

  const sessionKey = createSessionKey(req.body); // your logic
  res.json({ session_key: sessionKey });
});

Step 2: Build your iframe page (web)

Once the handshake succeeds, Hint loads your iframe URL and appends session_key as a query parameter.

At minimum:

load the SDK
call HintSDK.init() when ready
read context (HintSDK.user, HintSDK.currentPatient, etc.)

Minimal example:

<script src="https://api.sandbox.hint.com/hint-sdk.js"></script>

<script>
  const params = new URLSearchParams(window.location.search);
  const sessionKey = params.get("session_key"); // your session identifier

  function render() {
    const user = HintSDK.user;
    const patient = HintSDK.currentPatient;
    document.getElementById("session").textContent = sessionKey || "(missing)";
    document.getElementById("user").textContent = user ? user.email : "(missing)";
    document.getElementById("patient").textContent = patient ? patient.name : "(none selected)";
  }

  HintSDK.init(() => render());
  HintSDK.onCurrentPatientChanged(() => render());
</script>

<div style="font-family: ui-sans-serif, system-ui; padding: 16px">
  <h2>Inventory app (quickstart)</h2>
  <p><b>session_key</b>: <span id="session"></span></p>
  <p><b>user</b>: <span id="user"></span></p>
  <p><b>patient</b>: <span id="patient"></span></p>

  <button onclick="HintSDK.close()">Close</button>
</div>

Next: make it a real workflow

Once the quickstart works:

When HintSDK.currentPatient changes, show recommendations in context.
Store your own records keyed by practice and patient IDs.
Use the access_token from the handshake session to call Hint APIs and record actions with a user audit trail.