Authentication
The SmileCloud Public API authenticates every request with a per-clinic secret key, presented as an HTTP bearer token. There are no sessions, cookies, or OAuth flows for v1 - a single key both identifies the clinic and carries the scopes that gate access.
#API keys
Keys are opaque, randomly generated strings prefixed with sk_live_:
sk_live_4f8a2c9e1b7d6a3f0e5c8b2a9d4f7e1c
Each key belongs to exactly one clinic. SmileCloud stores only a SHA-256 hash of the key - the plaintext is shown once at creation and can never be retrieved again. If a key is lost, revoke it and mint a new one.
#Authorizing a request
Send the key in the Authorization header on every request:
curl https://api.smile-app.co.il/v1/me \
-H "Authorization: Bearer sk_live_..."
The same bearer key works across all three surfaces - REST, the MCP server at /mcp, and the sc CLI.
Keep keys server-side
Because a key carries read access to clinic data, it must only ever live in a trusted backend or a secured operator environment. Never ship a key in a browser bundle, a mobile app, or any client you don't fully control.
#Scopes
Every key carries a set of scopes - fine-grained permissions that decide which resources it can read. A request is allowed only if the key holds the scope that the endpoint requires.
| Scope | Grants access to |
|---|---|
patients:read | Patients and patient lookups |
appointments:read | Appointments |
availability:read | Free appointment slots |
treatments:read | Treatments performed/recorded |
payments:read | Payments and refunds |
catalog:read | Branches, types, statuses, treatments, providers |
webhooks:manage | Create, list, and delete webhook subscriptions |
You can inspect the scopes on the current key at any time with GET /v1/me. See Scopes for a deeper reference and a per-endpoint mapping.
#Errors
Authentication and authorization failures use standard status codes and the application/problem+json body described in Errors:
| Status | Meaning |
|---|---|
401 Unauthorized | The Authorization header is missing, malformed, or the key is invalid or revoked. |
403 Forbidden | The key is valid but lacks the scope the endpoint requires. |
{
"type": "https://api.smile-app.co.il/problems/forbidden",
"title": "Missing required scope",
"status": 403,
"detail": "This key needs the 'patients:read' scope."
}
#Rotating and revoking keys
- Rotate by minting a new key, deploying it, then revoking the old one - keys are independent, so there's no downtime.
- Revoke immediately if a key is exposed. Revocation takes effect on the next request.
Because keys are scoped per clinic, a compromised key can never reach another clinic's data.