Dazr Files API: documentazione per sviluppatori

Legga i file di Dazr Files nel Suo software, per esempio per farne il backup: un’API REST con un feed delle modifiche, e WebDAV per gli strumenti di backup. Sola lettura.

• Guida rapida
• Accesso dell’organizzazione
• I file personali di una persona
• Riferimento
• Backup incrementali
• Errori e limiti
• WebDAV

Guida rapida

1. Registri la Sua app e attivi la Dazr Files API. Registri la Sua app, o ne usi una che ha già, nella console di Dazr Identity: lo stesso posto di Accedi con Dazr Identity e della Dazr Sign API, con lo stesso Client ID e lo stesso secret. Nella pagina dell’app scelga Attiva Dazr Files API. Per backup non presidiati l’app deve essere un’app web server (con un client secret).
2. Ottenga l’approvazione. Dia all’organizzazione il Suo Client ID. Un titolare o un amministratore apre Dazr Identity → Organizzazioni → l’organizzazione → App collegate a Files, inserisce il Client ID e sceglie cosa può leggere la Sua app: tutti i file condivisi, o cartelle scelte con tutto il loro contenuto. Può anche limitare l’app a reti indicate (intervalli IP).
3. Ottenga un token. Il Suo server richiede un token con grant_type=client_credentials, l’id dell’organizzazione come org, e il Suo Client ID e secret (HTTP Basic o il corpo del modulo). Solo le app con un client secret possono farlo.
4. Chiami l’API. Invii il token di accesso come Authorization: Bearer. Dura 10 minuti e non c’è un refresh token: ne richieda uno nuovo quando scade.

curl -u "$DAZR_CLIENT_ID:$DAZR_CLIENT_SECRET" https://identity.dazr.eu/oauth/token \
  -d grant_type=client_credentials -d scope=files.read -d org=org_3k9x2m0q8w1v5t7a

{ "access_token": "eyJhbGciOiJFUzI1NiIs...", "token_type": "Bearer", "expires_in": 600, "scope": "files.read" }

curl -H "Authorization: Bearer $TOKEN" https://suite.dazr.eu/api/files/v1/spaces

Accesso dell’organizzazione per i backup

Ci sono due modi. Un titolare o un amministratore di un’organizzazione approva la Sua app per i file condivisi dell’organizzazione, e il Suo server ottiene token senza una persona (ideale per backup non presidiati). Oppure una persona autorizza la Sua app con lo scope files.read, e l’app legge i file personali di quella persona.

Un’organizzazione che non ha approvato la Sua app, una che l’ha revocata e una che non esiste rispondono tutte invalid_grant. Gli amministratori vedono quando l’app è stata usata l’ultima volta e ogni file che ha scaricato, e possono modificarne le cartelle o revocarla in qualsiasi momento. Un’approvazione revocata si ferma alla richiesta successiva: i token già emessi smettono subito di funzionare, e così i link di download già forniti. I file personali dei membri non fanno mai parte dell’approvazione di un’organizzazione.

I file personali di una persona

Richieda openid files.read (e offline_access per un refresh token) nel consueto flusso authorization code con PKCE. La persona vede nella schermata di consenso che l’app può vedere e scaricare i suoi file. Il token raggiunge i suoi file personali, e i file condivisi di un’organizzazione solo se anche quell’organizzazione ha approvato l’app e la persona è un membro che può aprirli, con le stesse cartelle. Quando la persona rimuove l’app in App collegate, i token smettono di funzionare.

Riferimento

URL di base https://suite.dazr.eu/api/files/v1. Ogni endpoint è GET (e HEAD); qualsiasi altro metodo risponde 405. Gli errori sono JSON: { "error": { "code", "message" } }. Gli elenchi accettano limit (da 1 a 1000, predefinito 200) e restituiscono next_cursor finché ce ne sono altri.

Ogni richiesta richiede lo scope files.read. Parametri di query:

GET /spaces
{ "spaces": [ { "id": "org_3k9x2m0q8w1v5t7a", "type": "organisation", "name": "Bakkerij Jansen", "folders": "chosen" } ] }

GET /spaces/org_3k9x2m0q8w1v5t7a/folders/root/children?limit=2
{ "items": [
    { "id": "Hk2mQ9xP4aL1", "type": "folder", "name": "Finance", "parent_id": null, "path": "/Finance",
      "created_at": "2026-09-01T08:12:40.000Z" },
    { "id": "p3RtY7uW0zQe", "type": "file", "name": "Budget 2027.xlsx", "parent_id": "Hk2mQ9xP4aL1",
      "path": "/Finance/Budget 2027.xlsx", "size": 48213,
      "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "version": 3, "version_count": 3,
      "etag": "\"p3RtY7uW0zQe.3.48213\"", "sha256": null, "created_at": "2026-09-02T10:00:00.000Z",
      "modified_at": "2026-10-14T16:31:09.000Z", "trashed_at": null } ],
  "next_cursor": "o.2" }

GET /spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/versions
{ "versions": [ { "version": 3, "size": 48213, "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                  "created_at": "2026-10-14T16:31:09.000Z", "current": true, "restored_from": null } ] }

GET /spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/content
302 Found
Location: https://files.dazr.eu/v1/file?t=g1.…

curl -L -o "Budget 2027.xlsx" -H "Authorization: Bearer $TOKEN" \
  https://suite.dazr.eu/api/files/v1/spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/content

Segua il reindirizzamento (curl -L): il link su files.dazr.eu non richiede l’header Authorization. Un file non ancora presente nel gateway di Files viene trasmesso direttamente invece di essere reindirizzato.

Checksum: Dazr Files non conserva un hash del contenuto di ogni file, quindi sha256 è sempre null. L’etag cambia ogni volta che cambia il contenuto (una nuova versione). Se Le serve un hash, lo calcoli durante il download. I file sono conservati cifrati (AES-256-GCM, con una chiave per spazio custodita da Dazr) e Dazr li decifra quando li scarica tramite TLS. Non è una cifratura end-to-end.

Backup incrementali

Chiami changes una prima volta senza cursore: ogni cartella e ogni file torna come created, con un cursor. Conservi il cursore e lo invii la volta successiva come cursor=. Riceve ciò che è cambiato da allora: created, updated (nuovo contenuto), moved (rinominato o spostato in un’altra cartella), trashed, restored e deleted (eliminato definitivamente, o non più nelle cartelle che l’app può leggere). Ogni modifica ha l’id, l’item_type e l’item attuale (null se eliminato). Le cartelle vengono prima dei file, i genitori prima dei figli. Finché has_more è true, richiami con il nuovo cursore. Se non è cambiato nulla, riceve lo stesso cursore. Un cursore vale 90 giorni, solo per la Sua app e quello spazio; uno scaduto risponde 410, e si ricomincia senza cursore. Restano validi solo i 5 cursori più recenti della Sua app per uno spazio.

GET /spaces/org_3k9x2m0q8w1v5t7a/changes?cursor=dc1.ds_…
{ "changes": [
    { "type": "updated", "id": "p3RtY7uW0zQe", "item_type": "file",
      "item": { "id": "p3RtY7uW0zQe", "type": "file", "name": "Budget 2027.xlsx", "version": 4, … } },
    { "type": "deleted", "id": "Zx81LmQa2bNc", "item_type": "file", "item": null } ],
  "cursor": "dc1.ds_…",
  "has_more": false }

Errori e limiti

Gli errori hanno uno stato HTTP e un corpo come { "error": { "code": "not_found", "message": "..." } }. Tutto ciò che il token non raggiunge risponde 404, come ciò che non esiste.

L’endpoint del token risponde con errori OAuth: invalid_client (Client ID o secret errati, o un’app senza client secret), unauthorized_client (la Dazr Files API non è attiva per l’app), invalid_scope e invalid_grant (nessuna approvazione di quell’organizzazione, o non dalle sue reti indicate).

Ogni download viene registrato per gli amministratori dell’organizzazione con il nome dell’app, il file, l’ora e parte dell’indirizzo IP: gli ultimi 5.000, fino a 180 giorni. Lo stesso file scaricato di nuovo entro 10 minuti conta una volta. L’attività di Files dell’organizzazione mostra una riga al giorno per la Sua app. I download dai file personali di una persona compaiono nelle sue App collegate.

WebDAV

Per gli strumenti di backup che usano WebDAV, un amministratore dell’organizzazione crea un accesso WebDAV per la Sua app in App collegate a Files. La password viene mostrata una volta, è conservata solo come hash e non è mai la password Dazr di qualcuno. L’accesso segue l’approvazione: stesse cartelle, reti e limiti, e si ferma quando l’approvazione viene revocata.

I nomi di cartelle e file sono mostrati come sono in Dazr Files. Quando due elementi di una cartella hanno lo stesso nome (senza distinguere maiuscole e minuscole), il più vecchio lo mantiene e gli altri ricevono il loro id tra parentesi prima dell’estensione, così ogni elemento ha un proprio percorso. Una cartella con più di 10.000 elementi non può essere elencata via WebDAV; per quella usi l’API. Dopo 10 accessi falliti da un indirizzo IP entro 15 minuti, quell’indirizzo attende 15 minuti.

rclone

1. Esegua rclone config, scelga n per un nuovo remote, lo chiami dazr e scelga il tipo di archiviazione webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: il nome utente (dzw_…). Password: scelga di digitarla e incolli la password.
3. Lasci vuoto il bearer token e salvi. Verifichi con rclone lsd dazr:, poi esegua il backup.

# ~/.config/rclone/rclone.conf (rclone obscure <password> gives the pass value)
[dazr]
type = webdav
url = https://files.dazr.eu/dav/
vendor = other
user = dzw_0123456789abcdef0123
pass = <obscured password>

rclone lsd dazr:
rclone sync dazr: /backup/dazr --transfers 4

rclone confronta dimensione e ora di modifica. Usi copy invece di sync per mantenere nel backup i file eliminati in Dazr Files.

Synology Cloud Sync

1. Apra Cloud Sync sul NAS, aggiunga un provider cloud e scelga WebDAV.
2. Indirizzo del server: https://files.dazr.eu/dav/. Nome utente e password: l’accesso WebDAV fornito dall’amministratore.
3. Scelga una cartella locale, la cartella remota / (o una cartella) e la direzione di sincronizzazione Download remote changes only.

Cloud Sync con WebDAV, direzione di sincronizzazione “Download remote changes only”. Hyper Backup scrive backup su WebDAV ma non può leggerne.