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.

Types	Workflow
Automatic	A user will be directed to your app's sign in or sign up page with a connection code in the url to use with our api to complete the activation process.
Headless	We post information about a new practice to your server, you can provision or link and them complete the activation. We can redirect the user to a specific location once completed such as an embedded app page within the Hint app.
Manual (Not Recommended)	When installed the user is shown an authorization code they provide to your team. You exchange that via the api to complete the activation process and acquire a practice api key.

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 a request to POST /api/oauth/tokens with the authorization code. The response includes a practice-scoped access token. If you will provision an account in headless mode you can now do a GET /provider/practices to get the account informaton.

Example response:

{
  "id": "int-j21vwWTG0EiP",
  "status": "connected",
  "token_type": "bearer",
  "refresh_token": null,
  "expires_in": null,
  "practice": {
    "id": "pra-TeDmP0gqGJLZ",
    "name": "Joe's Practice"
  },
  "access_token": "IpT6ucPNhRhDEeZcBNVKnoSSBNS1i6QplR4"
}

Store the access token securely and associate it with the practice inside your system. All /api/provider/* calls for that practice should now use the returned token.

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

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.