Scopes

Scopes are the permission system for API keys. Each key carries a set of scopes, and each endpoint requires exactly one. A request succeeds only when the key holds the endpoint's required scope; otherwise it returns 403 Forbidden.

#Available scopes

Scope	Description
`patients:read`	Read patients, search, and per-patient lookups.
`appointments:read`	Read appointments and a patient's appointments.
`availability:read`	Read free appointment slots.
`treatments:read`	Read treatments performed/recorded for patients.
`payments:read`	Read payments and refunds.
`payments:write`	Record a payment and issue its accounting documents. Granted explicitly — never bundled with reads.
`leads:write`	Capture CRM leads from external channels (website forms, bots, Zapier). Create-only — there is no `leads:read`.
`calls:read`	Read the phone call log, AI summaries, transcripts and recording links.
`catalog:read`	Read reference data: branches, types, statuses, treatments, providers.
`analytics:read`	Run aggregations and describe queryable metrics (`/v1/query`, `/v1/metrics`).
`webhooks:manage`	Create, list, inspect, and delete webhook subscriptions.

#Endpoint mapping

Endpoint	Required scope
`GET /v1/me`	(none - any valid key)
`GET /v1/patients`, `/v1/patients/{id}`	`patients:read`
`GET /v1/patients/{id}/appointments`	`appointments:read`
`GET /v1/patients/{id}/treatments`, `/v1/treatments/{id}`	`treatments:read`
`GET /v1/patients/{id}/payments`, `/v1/payments/{id}`	`payments:read`
`POST /v1/patients/{id}/payments`	`payments:write`
`POST /v1/leads`	`leads:write`
`GET /v1/calls`, `/v1/calls/{id}`, `/v1/calls/{id}/recording`, `/v1/patients/{id}/calls`	`calls:read`
`GET /v1/appointments`, `/v1/appointments/{id}`	`appointments:read`
`GET /v1/availability`	`availability:read`
`GET /v1/catalog/*`	`catalog:read`
`GET /v1/metrics`, `POST /v1/query`	`analytics:read` (+ a measure's own scope, e.g. `payments:read`, for financial measures)
`POST/GET/DELETE /v1/webhooks`, deliveries, retry	`webhooks:manage`
`POST /mcp` tools	the matching `*:read` scope per tool

Least privilege

Mint keys with only the scopes an integration actually needs. A reporting script that reads appointments shouldn't carry payments:read. Narrow keys limit blast radius if one is ever exposed.

#Checking a key's scopes

Call GET /v1/me to see the clinic and scopes attached to the current key:

curl https://api.smile-app.co.il/v1/me \
  -H "Authorization: Bearer sk_live_..."

{
  "data": {
    "clinic_id": "demo",
    "scopes": ["catalog:read", "appointments:read"]
  }
}

For AI agents, smile_whoami exposes the same information so the agent can discover its limits up front instead of probing endpoints and hitting 403s.