Skip to content
FibonacciMedicaLog inTry it free

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 https return addresses: where the browser goes back after consent;
  • the public https address 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.

PermissionWhat you can doWhat you do not see
agenda-letturaread and search Schedule, Slot, Location; read an Appointment by codepatient name, phone and email, treatment, reason, appointment notes
agenda-scritturacreate an Appointment and change its time or status, only in the states booked, pending, cancelledas above; no deleting, no searching
richiestecreate an Appointment in the pending state: the practice finds it among the requests and decidesit cannot be read back or modified
recapitiread a Patient by codeeverything except name, phone and email (no date of birth, tax code, address)
fatture-letturaread and search Invoicethe 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>
    

    state is 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 Connect next to your app. In this case there is no state, 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:

ParameterWhat it is
client_idthe code of your app in that practice: each practice has its own
issthe practice’s FHIR base, for example https://app.fibonaccimedica.it/api/projects/<studio>/fhir/R4
token_urlwhere to ask for the token: https://app.fibonaccimedica.it/api/projects/<studio>/oauth2/token
stateyour 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:

FieldValue
issthe practice’s client_id
subthe practice’s client_id
audthe practice’s token_url, exactly as it reached you
iatnow, in Unix seconds
expat most 5 minutes after iat
jtia 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:

WhatHow
read by codeGET <Type>/<id> for Schedule, Slot, Location, Appointment, Patient, Invoice
searchGET Schedule?, Slot?, Location?, Invoice? with the parameters in the table below
create an appointmentPOST Appointment
change an appointmentPUT Appointment/<id> (send the resource you read, with the changed fields)
server capabilitiesGET metadata
TypeAllowed search parameters
Scheduleactor, active, date, _id, _count, _offset, _sort, _lastUpdated
Slotschedule, start, status, _id, _count, _offset, _sort, _lastUpdated
Locationstatus, _id, _count, _offset
Invoicedate, 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

ResponseWhat it means
400 from the token, invalid_requestthe 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_typeclient_credentials with client_assertion is needed; a client_secret is not enough
401token expired: ask for a new one
400 with Authentication errorthe 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-ammessothe call is not among those in point 3.4
403 without a codethe call is allowed but the permission is not: the practice has not granted it
405 with metodo-non-ammessoHTTP verb not provided for that type
503 with registro-non-disponibilewe 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).