Integration Activation

Activation is how a practice enables your integration and authorizes your system to access practice-scoped data in Hint.

Activation Options

We recommend implementing an automatic connection so practices can self-serve activation from inside Hint to get started immediately. We additionally support a headless option for partners who don't need users to sign in directly with them, or want to use Hint's User & Role management directly.

Activation modes (when the connection goes live)

The authentication method above controls how you receive the authorization code. A separate product setting -- the activation mode -- controls when the connection becomes active (an active connection sends webhooks and, if you bill through Hint, starts billing).

The activation mode does not change the credential exchange: every headless connection delivers the authorization code and lets you exchange it for a practice API key regardless of mode -- so you can always provision the account and read practice data. The mode only decides who flips the connection live, and when.

In the two non-instant modes you receive the connection (and its authorization code) before it is active. Exchange the code with activate: false (see Step 3) to provision the account and store the practice API key without flipping the connection live, then activate later:

• practice_activate: the practice activates from Hint -- you don't call activate.
• partner_activate: your staff activate through your own system, which calls POST /api/partner/installations/:id/activate.

List installations awaiting your action with GET /api/partner/installations?status=pending.

Step-by-step implementation

1. Practice initiates the connection

A practice admin opens your product inside the Hint Marketplace and clicks Install.

2. Hint redirects with an authorization code

Hint redirects the admin (or sends a request in headless) to the redirect_url you registered during onboarding and appends an authorization code.

🚧

Validate the redirect target

We append the authorization code immediately to your URL. Build defensively - validate the host, enforce HTTPS, and make sure you only process codes that map to valid sessions inside your app.

3. Exchange the code for practice credentials

Send the authorization code to POST /api/partner/installations/connect. Hint finds the installation for that code and returns it together with its practice credential (an API key) -- so you get the connection record and its key in a single call.

The activate flag decides whether the exchange also flips the connection live:

• activate: true (the default) -- exchange the code and activate the connection. Use this for instant-style flows.
• activate: false -- exchange the code without activating. Use this in partner_activate mode to provision the account and store the key while the installation stays pending, then activate later with POST /api/partner/installations/:id/activate.

Request:

{
  "code": "authorization-code-from-redirect",
  "activate": true
}

Example response (installation + credential):

{
  "id": "inst-9pQ2xR7mDkLZ",
  "status": "active",
  "practice": {
    "id": "pra-TeDmP0gqGJLZ",
    "name": "Joe's Practice"
  },
  "product": {
    "id": "pp-4vNbGh1Yko6P",
    "name": "Acme Health Connect"
  },
  "api_keys": [
    {
      "label": "Joe's Practice",
      "token": "IpT6ucPNhRhDEeZcBNVKnoSSBNS1i6QplR4"
    }
  ]
}

Store the api_keys[].token securely and associate it with the practice inside your system. All /api/provider/* calls for that practice use this token as the Bearer credential. If you provision an account in headless mode you can now call GET /api/provider/practices to fetch the account information.

Token handling expectations

• Store one access token per practice
• Treat tokens as secrets (encrypt at rest, least privilege access)
• Support reconnect for installing with existing customers, or when a practice disables/re-enables the integration

Managing connections

Each practice connection is modeled as an installation -- one practice's connection to one of your products (the record returned by connect in Step 3). Installations give you a per-connection view of each practice:

• GET /api/partner/installations lists your connections; filter by status (onboarding, pending, active, deactivated) or by product.
• GET /api/partner/installations/:id returns a single connection, including the practice it belongs to.
• POST /api/partner/installations/:id/activate and POST /api/partner/installations/:id/deactivate control that connection. Activate/deactivate act on the individual installation (per product), so deactivating one product's connection does not affect the practice's other installed products.

Per-connection API keys and webhook endpoints are addressed through the installation. Because every product a practice installs on the same backend shares one underlying connection, these credentials and endpoints are shared across that practice's installations -- a key created through one installation is visible on its siblings, and deleting it removes it for all.

Manual activation

Some partners start with a manual activation workflow. In this flow the practice admin will be shown the code in Hint, and will need to manually provide it to the partner. The remaining steps are the same for exchanging the code for an api key.