For developers: connecting your app to Fibonacci
9 min readUpdated on 15 November 2026
This guide is for companies that want to connect one of their programs (a switchboard, online booking, an accounting or reminder app) to the practices that use Fibonacci. The practice sees your app in Settings, Connections, presses Connect, reads what it will be able to do and confirms. From then on your app gets a token and calls the practice’s APIs, only for what the practice has granted. The practice can disconnect it whenever it wants, and from that moment your tokens stop working.
We use standards, with no protocols of our own: OAuth 2.0 with the SMART Backend Services profile (a JWT signed with your private key, RFC 7523) and the FHIR R4 APIs. No shared secret passes between us and you.
1. Registering the app
For now we register and approve apps ourselves, one by one. Write to us from the Partner page or at info@fibonaccimedica.it with:
- the app name and the company name, as the practice will see them;
- the website and a support contact (an email, and a page if there is one): the practice reads them on the consent screen;
- a description of two lines on what the app does for the practice, in Italian (and in the other languages, if you have them);
- one or more
httpsreturn addresses: where the browser goes back after consent; - the public
httpsaddress of your public keys (JWKS, RFC 7517); - the permissions you need, among those in point 2, and why.
When the app is approved, we first put it in a test practice with fake data (point 6), and only after that do practices see it.
Return addresses are compared character by character: no prefixes, no extra parameters. An address different from the registered ones makes the connection fail.
2. The permissions
There are five and they are closed. The practice sees them written in plain words before confirming. No clinical data leaves: medical history, visits, treatments, photos, consents and reports stay inside.
| Permission | What you can do | What you do not see |
|---|---|---|
agenda-lettura | read and search Schedule, Slot, Location; read an Appointment by code | patient name, phone and email, treatment, reason, appointment notes |
agenda-scrittura | create an Appointment and change its time or status, only in the states booked, pending, cancelled | as above; no deleting, no searching |
richieste | create an Appointment in the pending state: the practice finds it among the requests and decides | it cannot be read back or modified |
recapiti | read a Patient by code | everything except name, phone and email (no date of birth, tax code, address) |
fatture-lettura | read and search Invoice | the invoice lines (they reveal the treatment), the notes, the extensions (tax code, payment), the doctor |
Hidden fields do not appear in responses. When you change an appointment, Medplum puts the hidden fields back as they were: do not delete them by sending the resource without them.
3. The connection, step by step
3.1 The practice connects you
The flow can start from two places.
-
From your website. Send whoever administers the practice to:
https://app.fibonaccimedica.it/impostazioni/collegamenti/app/<vostra-app>?redirect_uri=<indirizzo-di-ritorno>&state=<valore-casuale>stateis a random value of yours, at most 200 characters among letters, digits and-._~: it comes back unchanged and is used to recognise the request (against cross-site request forgery). -
From Fibonacci. The practice presses
Connectnext to your app. In this case there is nostate, and the return is the first registered address.
If whoever opens the link is not signed in, Fibonacci asks them to sign in and then takes them back to the consent screen. Only whoever administers the practice can confirm.
3.2 The return
Once consent is confirmed, the browser goes back to your return address with four parameters:
| Parameter | What it is |
|---|---|
client_id | the code of your app in that practice: each practice has its own |
iss | the practice’s FHIR base, for example https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4 |
token_url | where to ask for the token: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token |
state | your value, if you had sent one |
Check state, then save client_id, iss and token_url next to the practice’s account on your system. None of the three is a secret: without your private key they are of no use to anyone.
3.3 The token
Sign a JWT with your private key (algorithms ES256, ES384, ES512, RS256, RS384, RS512; ES256 or ES384 recommended), with kid in the header equal to a key in your JWKS:
| Field | Value |
|---|---|
iss | the practice’s client_id |
sub | the practice’s client_id |
aud | the practice’s token_url, exactly as it reached you |
iat | now, in Unix seconds |
exp | at most 5 minutes after iat |
jti | a unique value for each JWT |
Then:
curl -X POST "$TOKEN_URL" \
-d grant_type=client_credentials \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
-d client_assertion="$JWT"
The response is a Bearer token that lasts an hour. There is no refresh token: when it expires you ask for another with a new JWT. A shared secret (client_secret) is not accepted.
An example in Python, with the PyJWT library:
import time, uuid, jwt, httpx
def token(client_id: str, token_url: str, chiave_privata_pem: str, kid: str) -> str:
ora = int(time.time())
assertion = jwt.encode(
{"iss": client_id, "sub": client_id, "aud": token_url, "iat": ora, "exp": ora + 240, "jti": uuid.uuid4().hex},
chiave_privata_pem, algorithm="ES256", headers={"kid": kid},
)
r = httpx.post(token_url, data={
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": assertion,
})
r.raise_for_status()
return r.json()["access_token"]
3.4 The calls
With the token, you call the practice’s iss base:
curl -H "Authorization: Bearer $TOKEN" "$ISS/Slot?schedule=Schedule/<id>&start=ge2026-12-01"
curl -H "Authorization: Bearer $TOKEN" "$ISS/Appointment/<id>"
The token is valid only on that practice’s addresses (.../projects/<studio>/...). The allowed calls are these:
| What | How |
|---|---|
| read by code | GET <Type>/<id> for Schedule, Slot, Location, Appointment, Patient, Invoice |
| search | GET Schedule?, Slot?, Location?, Invoice? with the parameters in the table below |
| create an appointment | POST Appointment |
| change an appointment | PUT Appointment/<id> (send the resource you read, with the changed fields) |
| server capabilities | GET metadata |
| Type | Allowed search parameters |
|---|---|
Schedule | actor, active, date, _id, _count, _offset, _sort, _lastUpdated |
Slot | schedule, start, status, _id, _count, _offset, _sort, _lastUpdated |
Location | status, _id, _count, _offset |
Invoice | date, status, identifier, type, _id, _count, _offset, _sort, _lastUpdated |
_count goes from 1 to 100. Chained searches (patient.name=), modifiers (:missing, :text), _include, _revinclude, _has, $ operations, _history and batch requests are not allowed: they answer 403. On Appointment and Patient there is no search, on purpose: even without showing a field, a search on that field would tell you whether it is there or not.
To know which appointments exist without searching for them, use notifications (point 4).
4. Notifications
When an appointment is created, changes time or status, or is cancelled, Fibonacci can send a signed message to an https address of yours, with the event type (appuntamento.creato, appuntamento.modificato, appuntamento.annullato), the codes and the dates. The message does not contain the patient’s name. The signature is in the X-Fibonacci-Firma header (HMAC-SHA256 of the time and of the exact body).
For now the address is added by the practice, from Settings, People and permissions, Access for outside programs, Notifications, and the signing secret is shown to it only once. The format and the signature check are in the technical guide on external access, which we send you with the registration. Having notifications switch on by themselves with the app’s connection is the next step, not done yet.
5. Errors
| Response | What it means |
|---|---|
400 from the token, invalid_request | the JWT is wrong: aud different from token_url, exp expired or too far away, a signature that does not match your JWKS, or the app is no longer connected |
400 from the token, unsupported_grant_type | client_credentials with client_assertion is needed; a client_secret is not enough |
401 | token expired: ask for a new one |
400 with Authentication error | the practice has disconnected the app: the token no longer works, and no new ones can be obtained (Client not found from the token endpoint) |
403 with percorso-non-ammesso, tipo-non-ammesso, parametro-non-ammesso | the call is not among those in point 3.4 |
403 without a code | the call is allowed but the permission is not: the practice has not granted it |
405 with metodo-non-ammesso | HTTP verb not provided for that type |
503 with registro-non-disponibile | we could not write the access to the log, and without the log the data does not leave: try again shortly |
FHIR errors arrive as an OperationOutcome, with the code in issue[0].details.text.
6. The test practice
Before a real practice, your app connects to a test practice with fake data: we prepare it when we register the app, and there you go through the whole flow (consent, return, token, calls, disconnection). No real patients, no real data.
7. What stays recorded
Every token your app obtains and every call it makes go into the practice’s access log, in your app’s name: what, when, with what outcome, and for which patient when there is one. The practice reads it from its log. Connecting and disconnecting are recorded too, with the name of who did them.
8. Privacy and contract
The practice is the controller of its patients’ data; your app processes it on its behalf. Before a real practice connects you, an agreement between you and the practice on data processing is needed (art. 28 of the GDPR): the consent screen reminds the practice of this. Ask for and keep only the data you need.
9. Support
For registration, the test practice and any technical doubt: info@fibonaccimedica.it. Give the app name and, if the error concerns a practice, the client_id (never the private key or a token).