Scopes
The permission areas a developer app can request, what each covers, and which webhook events it admits.
A developer app asks for areas of practice data, each as .read or
.write. Write includes read. A token's scopes cap what the authorising
member's role allows — they never widen it — and an area never reaches the
clinical record, billing, the account, or the platform admin surfaces.
Practices see the requested areas on the consent screen. Ask for what the app needs and no more; a reviewer will ask why otherwise.
| Area | Covers | Webhook events it admits |
|---|---|---|
patients | Patients and their activity timeline | patient.*, pms_patient.link_changed |
appointments | Appointments, locations, practitioners, the waitlist | appointment.* |
journeys | Journeys (enquiries and treatment pipelines), pipelines, leads | journey.*, lead_ad_submission.* |
tasks | Tasks | task.* |
conversations | Conversations and messages | conversation.*, message.* |
treatments | The treatment catalogue | pms_treatment_plan.updated |
campaigns | Campaigns, message templates, automation sequences | — |
deposits | Deposit requests and payment settings | deposit_request.*, pms_invoice.updated, pms_payment.updated |
reputation | Review requests, feedback, reviews and replies | reputation_* |
reports | Reports and report subscriptions | — |
webhooks | The practice's outbound webhook endpoints | — |
settings | Practice settings | lead_ad_connection.health_changed, pms_connection.health_changed, pms_sync.review_required, channel_connection.health_changed |
Add offline_access to receive a refresh token. Without it a connection ends
when its one-hour access token expires.
How a scope is checked
Every request is checked twice:
- The route family must belong to one of the token's areas, so an area token never reaches an unrelated part of the API at all.
- The route's own permission (for example
patient:create) must be covered by a held area of the right class, and then by the authorising member's role.
A request outside the token's scopes answers 403 with
code: "INSUFFICIENT_SCOPE". A request the member's role forbids answers the
usual 403 permission error.
Scope strings
The scope parameter is a space-separated list, for example
patients.read appointments.write offline_access. An app can only request the
areas it was published with; anything else answers invalid_scope at the
authorise step.
Connect a practice with OAuth
The authorization-code flow with PKCE against Smileline's global authorise and token URLs, and what to keep from the token response.
App webhooks
One delivery URL and signing secret per app; how Smileline materialises a verified endpoint for every connected practice and what it sends.