> ## Documentation Index
> Fetch the complete documentation index at: https://build.practicehub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Administering AI connectors

> Who can connect an assistant, what it can do, and how to see and revoke access

An AI connector is not a separate account — it's a team member's own PracticeHub login, used by an assistant instead of a browser. Everything in this page is about controlling that: who is allowed to connect one, what it can then do, and how to switch it off.

<Note>
  Connectors are a PracticeHub 2.0 platform feature. If nobody in your account can see **Developers → API Keys**, the platform hasn't been switched on for you yet and role permissions below won't matter until it is.
</Note>

<Note>
  **During the limited rollout, connectors are read-only** — the server exposes no write tools, so a connector can look things up but cannot book, take payments or change records regardless of the role behind it. The write-permission rules below describe how roles will govern writes once write access is switched on; the read-side rules (visibility, own-patients and own-calendar ringfences) apply today.
</Note>

## Who can connect

Connecting an AI app is **opt-in per role**:

* **Account owners and super users** can always connect one — this is implicit and can't be switched off.
* **Everyone else** needs their role to have **Connect AI apps (Claude, ChatGPT)** turned on, under **Settings → Security → Roles**.

<Steps>
  <Step title="Open the role">Settings → Security → Roles, then the role you want to allow (e.g. "Front Desk", "Practitioner").</Step>
  <Step title="Turn on the toggle">Find **Connect AI apps (Claude, ChatGPT)** and switch it on. This only grants the ability to *start* a connection — it doesn't grant any new read/write powers by itself.</Step>
  <Step title="Save">The team member can now add PracticeHub as a connector from their own AI app; see [Connectors](/mcp/connectors) for the steps you'd hand them.</Step>
</Steps>

If someone without this permission tries to connect anyway, they land on a PracticeHub page that tells them plainly that their role doesn't allow it yet and names the toggle to ask for — not a cryptic error.

Turning the toggle back off, or deactivating the team member's account, cuts off every connector they'd already approved on the very next call — nothing needs to be separately revoked first.

## What a connected assistant can and cannot do

A connector **acts as the team member who approved it, with their PracticeHub role** — never more than that person could do by hand in PracticeHub. There's no separate "AI permission level": the same role permissions that govern the app govern the assistant.

* **Reads follow the role.** Appointments and availability need calendar access; invoices, payments and allocations need *View all patient financial data*; clinical notes need *Patient visit notes* — the same toggle that shows or hides the notes tab in PracticeHub itself; most reference data and patient records are visible to any connected team member.
* **Writes will follow the role** (the assistant is read-only during the limited rollout, so none of this applies yet). Patients, files and patient-log notes need *Edit patient*; booking, moving or cancelling appointments needs calendar access (a read-only-calendar role can look but not touch); recording invoices and payments needs *Edit patient financials* (the same-day-only variant doesn't count); allocating payments needs *Allocate payments*; deleting anything needs the matching delete permission; changing settings-type data (locations, appointment types, referral sources, …) needs *Access settings*. **Clinical notes will need that same *Patient visit notes* permission to write, not just to read** — no separate write-side toggle; a role limited to draft-only notes will only create drafts through a connector too.
* **Restricted roles stay restricted.** A role limited to **own patients** only sees and edits patients where that person is the default practitioner — and can't create a new patient at all through a connector, since a new patient would have no default practitioner. A role limited to **own calendar** only sees that person's own diary and can only book or move appointments within it.
* **Account owners and super users hold every permission**, so nothing above narrows what they can do through a connector.

A refused action comes back to the assistant as a plain "your role doesn't allow this" message naming what's missing, so a good assistant reports it back to the person rather than working around it — see [Troubleshooting](/mcp/troubleshooting) if that's happening more than expected.

One thing is off the table for every role, owners included: **card payments** can't be recorded through the API — the terminal flow in PracticeHub is required. **Clinical/treatment notes** are governed by their own permission (*Patient visit notes*, **Settings → Security → Roles**) rather than *Edit patient* — a connector reads notes once the team member's role has it, and will create them (filed against one of the account's own note templates) when write access is switched on; the API doesn't create templates, and can't edit or delete a note once written.

## Seeing and revoking connections

**Developers → API Keys → Connected AI apps** lists every live connection as an app + team member pair (e.g. "Claude — Dana Scully"), with when it was approved. An account owner can revoke any row from there — including their own.

Revoking:

* Ends that connection's access **immediately** — its refresh token is revoked too, so the AI app can't silently mint a new access token and keep going.
* Doesn't touch the team member's PracticeHub login, or any other connector they may have approved separately (e.g. Claude and ChatGPT are revoked independently).

A connector also stops working, without anyone having to visit that page, the moment its team member's role loses the *Connect AI apps* permission or their PracticeHub account is deactivated.

Signing out of PracticeHub in a browser does **not** disconnect a connector — revoke it from **Connected AI apps**, or have the team member remove it from the AI app's own settings.

## What's audit-logged

Every connector-related credential event is written to the account's security activity log (**Reports → User Activity**, filter by category "security"):

| Event | When |
| - | - |
| `connector_authorised` | A team member approves a connection on the consent screen |
| `connector_revoked` | An owner revokes one from Connected AI apps |
| `api_key_created` / `api_key_rotated` / `api_key_revoked` | The equivalent events for API keys |

Beyond that, **every individual read or write a connector makes is logged like any other API call**, on **Developers → API Logs**, attributed to the team member it's acting as (not to "Claude" generically) — the same trail an API key's calls leave, just with a person's name on it instead of an integration's.

## Token lifetimes

* **Access tokens last one hour.** The AI app is expected to refresh silently in the background — a person using it shouldn't notice.
* **Refresh tokens last 30 days idle**, and rotate every time they're used. If a connector goes completely unused for 30 days, its refresh token lapses and the team member has to approve the consent screen again next time.
* Revoking a connection revokes both immediately, regardless of either lifetime above.

## Ground rules for a team using assistants

A few practical habits, matched to how the platform actually works:

* **Grant the permission per role, not to everyone.** Only turn on *Connect AI apps* for roles that should be able to look patient and diary information up through an assistant (and, once changes are switched on, book, edit or move things) — a read-only front-desk role, for instance, may not need it at all.
* **Ask assistants to confirm before writing.** Nothing in the platform requires this, but a well-behaved assistant should read back a booking, cancellation or payment before doing it. Say so explicitly in the first message of a conversation if yours doesn't.
* **Use the audit trail if something looks off.** API Logs shows exactly what a connector did and when, attributed to the person who approved it — check there before assuming an appointment or note was created by mistake.
* **Revoke on departure, not just deactivation.** Deactivating a leaving team member's account does cut off their connectors automatically, but revoking explicitly (and checking Connected AI apps is empty for them) is a good habit for a clean handover.
* **Treat a lost device like a lost password.** Revoke the connection from Connected AI apps immediately — it takes effect on the next call, no waiting for a token to expire.

See [Connectors](/mcp/connectors) for the step-by-step a team member follows to connect.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.