Dazr Files API: documentatie voor ontwikkelaars

Lees bestanden uit Dazr Files in je eigen software, bijvoorbeeld om er een back-up van te maken: een REST API met een wijzigingenfeed, en WebDAV voor back-uptools. Alleen lezen.

• Snel aan de slag
• Organisatietoegang
• Eigen bestanden van een persoon
• Naslag
• Incrementele back-ups
• Fouten en limieten
• WebDAV

Snel aan de slag

1. Registreer je app en schakel de Dazr Files API in. Registreer je app, of gebruik er een die je al hebt, in de Dazr Identity-console: dezelfde plek als voor Inloggen met Dazr Identity en de Dazr Sign API, met dezelfde client-ID en hetzelfde geheim. Kies op de pagina van je app Dazr Files API inschakelen. Voor onbeheerde back-ups moet het een webserver-app zijn (met een clientgeheim).
2. Laat je goedkeuren. Geef de organisatie je client-ID. Een eigenaar of beheerder opent Dazr Identity → Organisaties → de organisatie → Gekoppelde apps voor Files, vult de client-ID in en kiest wat je app mag lezen: alle gedeelde bestanden, of gekozen mappen met alles erin. Ze kunnen je app ook beperken tot opgegeven netwerken (IP-bereiken).
3. Vraag een token aan. Je server vraagt een token aan met grant_type=client_credentials, de organisatie-id als org, en je client-ID en geheim (HTTP Basic of de form body). Alleen apps met een clientgeheim kunnen dit.
4. Roep de API aan. Stuur het toegangstoken mee als Authorization: Bearer. Het is 10 minuten geldig en er is geen refreshtoken: vraag een nieuw token aan als het verloopt.

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

Organisatietoegang voor back-ups

Er zijn twee manieren. Een eigenaar of beheerder van een organisatie keurt je app goed voor de gedeelde bestanden van de organisatie, en je server krijgt dan tokens zonder een persoon (het beste voor onbeheerde back-ups). Of een persoon geeft je app toestemming met de scope files.read, en je app leest de eigen bestanden van die persoon.

Een organisatie die je app niet heeft goedgekeurd, een die de goedkeuring heeft ingetrokken en een die niet bestaat, antwoorden allemaal invalid_grant. De beheerders zien wanneer je app voor het laatst is gebruikt en elk bestand dat hij heeft gedownload, en kunnen de mappen op elk moment wijzigen of de app intrekken. Een ingetrokken goedkeuring stopt bij het volgende verzoek: al uitgegeven tokens werken meteen niet meer, en al uitgedeelde downloadlinks ook niet. De eigen bestanden van leden horen nooit bij de goedkeuring van een organisatie.

Eigen bestanden van een persoon

Vraag om openid files.read (en offline_access voor een refreshtoken) in de gewone authorization code flow met PKCE. De persoon ziet op het toestemmingsscherm dat je app de bestanden mag zien en downloaden. Het token bereikt de eigen bestanden van de persoon, en de gedeelde bestanden van een organisatie alleen als die organisatie je app ook heeft goedgekeurd en de persoon een lid is dat ze mag openen, met dezelfde mappen. Als de persoon je app verwijdert onder Gekoppelde apps, stoppen de tokens.

Naslag

Basis-URL https://suite.dazr.eu/api/files/v1. Elk endpoint is GET (en HEAD); elke andere methode antwoordt 405. Fouten zijn JSON: { "error": { "code", "message" } }. Lijsten nemen limit (1 tot 1000, standaard 200) en geven next_cursor zolang er meer is.

Elk verzoek heeft de scope files.read nodig. Queryparameters:

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

Volg de redirect (curl -L): de link op files.dazr.eu heeft geen Authorization-header nodig. Een bestand dat nog niet in de Files-gateway staat, wordt direct gestreamd in plaats van doorgestuurd.

Checksums: Dazr Files bewaart geen hash van de inhoud van elk bestand, dus sha256 is altijd null. De etag verandert telkens als de inhoud verandert (een nieuwe versie). Bereken zelf een hash tijdens het downloaden als je die nodig hebt. Bestanden worden versleuteld opgeslagen (AES-256-GCM, met een sleutel per space die Dazr beheert) en Dazr ontsleutelt ze als je ze via TLS downloadt. Dit is geen end-to-end-versleuteling.

Incrementele back-ups

Roep changes één keer aan zonder cursor: elke map en elk bestand komt terug als created, met een cursor. Bewaar de cursor en stuur hem de volgende keer mee als cursor=. Je krijgt wat er sindsdien is veranderd: created, updated (nieuwe inhoud), moved (hernoemd of naar een andere map verplaatst), trashed, restored en deleted (definitief weg, of niet meer in de mappen die je app mag lezen). Elke wijziging heeft de id, het item_type en het huidige item (null bij verwijderd). Mappen komen vóór bestanden, ouders vóór hun kinderen. Zolang has_more true is, roep je opnieuw aan met de nieuwe cursor. Als er niets is veranderd, krijg je dezelfde cursor terug. Een cursor werkt 90 dagen, alleen voor je app en die space; een verlopen cursor antwoordt 410, en je begint opnieuw zonder cursor. Alleen de 5 nieuwste cursors van je app per space blijven geldig.

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 }

Fouten en limieten

Fouten hebben een HTTP-status en een body zoals { "error": { "code": "not_found", "message": "..." } }. Alles wat je token niet bereikt, antwoordt 404, net als iets wat niet bestaat.

Het token-endpoint antwoordt met OAuth-fouten: invalid_client (verkeerde client-ID of geheim, of een app zonder clientgeheim), unauthorized_client (de Dazr Files API staat niet aan voor je app), invalid_scope en invalid_grant (geen goedkeuring van die organisatie, of niet vanaf de opgegeven netwerken).

Elke download wordt voor de beheerders van de organisatie gelogd met de naam van je app, het bestand, het tijdstip en een deel van het IP-adres: de laatste 5.000, maximaal 180 dagen. Hetzelfde bestand dat binnen 10 minuten opnieuw wordt gedownload, telt één keer. De Files-activiteit van de organisatie toont één regel per dag voor je app. Downloads uit de eigen bestanden van een persoon staan bij diens Gekoppelde apps.

WebDAV

Voor back-uptools die WebDAV spreken, maakt een beheerder van de organisatie een WebDAV-aanmelding voor je app aan onder Gekoppelde apps voor Files. Het wachtwoord wordt één keer getoond, wordt alleen als hash bewaard en is nooit iemands Dazr-wachtwoord. De aanmelding volgt de goedkeuring: dezelfde mappen, netwerken en limieten, en ze stopt als de goedkeuring wordt ingetrokken.

Map- en bestandsnamen worden getoond zoals ze in Dazr Files staan. Als twee items in een map dezelfde naam hebben (hoofdletters niet meegeteld), houdt het oudste die naam en krijgen de andere hun id tussen haakjes vóór de extensie, zodat elk item een eigen pad heeft. Een map met meer dan 10.000 items kan niet via WebDAV worden getoond; gebruik daarvoor de API. Na 10 mislukte aanmeldingen vanaf één IP-adres binnen 15 minuten moet dat adres 15 minuten wachten.

rclone

1. Voer rclone config uit, kies n voor een nieuwe remote, noem hem dazr en kies het opslagtype webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: de gebruikersnaam (dzw_…). Password: kies ervoor het zelf te typen en plak het wachtwoord.
3. Laat het bearer token leeg en sla op. Controleer met rclone lsd dazr: en maak dan de back-up.

# ~/.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 vergelijkt grootte en wijzigingstijd. Gebruik copy in plaats van sync om bestanden in je back-up te houden die in Dazr Files zijn verwijderd.

Synology Cloud Sync

1. Open Cloud Sync op de NAS, voeg een cloudprovider toe en kies WebDAV.
2. Serveradres: https://files.dazr.eu/dav/. Gebruikersnaam en wachtwoord: de WebDAV-aanmelding van de beheerder.
3. Kies een lokale map, de externe map / (of één map) en de synchronisatierichting Download remote changes only.

Cloud Sync met WebDAV, synchronisatierichting “Download remote changes only”. Hyper Backup schrijft back-ups naar WebDAV, maar kan er niet van lezen.