Dazr Files API: Entwicklerdokumentation

Lesen Sie Dateien aus Dazr Files in Ihrer eigenen Software, zum Beispiel um sie zu sichern: eine REST API mit Änderungsfeed und WebDAV für Backup-Tools. Nur lesen.

• Schnellstart
• Organisationszugriff
• Die eigenen Dateien einer Person
• Referenz
• Inkrementelle Backups
• Fehler und Grenzen
• WebDAV

Schnellstart

1. Registrieren Sie Ihre App und aktivieren Sie die Dazr Files API. Registrieren Sie Ihre App, oder verwenden Sie eine vorhandene, in der Dazr Identity-Konsole: am selben Ort wie für Anmelden mit Dazr Identity und die Dazr Sign API, mit derselben Client-ID und demselben Secret. Wählen Sie auf der Seite Ihrer App Dazr Files API aktivieren. Für unbeaufsichtigte Backups muss es eine Webserver-App sein (mit Client-Secret).
2. Lassen Sie sich freigeben. Geben Sie der Organisation Ihre Client-ID. Ein Inhaber oder Admin öffnet Dazr Identity → Organisationen → die Organisation → Verbundene Apps für Files, gibt die Client-ID ein und wählt, was Ihre App lesen darf: alle geteilten Dateien oder ausgewählte Ordner mit allem darin. Ihre App kann auch auf angegebene Netzwerke (IP-Bereiche) beschränkt werden.
3. Fordern Sie ein Token an. Ihr Server fordert ein Token mit grant_type=client_credentials, der Organisations-id als org und Ihrer Client-ID und Ihrem Secret an (HTTP Basic oder im Formular-Body). Das können nur Apps mit Client-Secret.
4. Rufen Sie die API auf. Senden Sie das Zugriffstoken als Authorization: Bearer. Es gilt 10 Minuten, und es gibt kein Refresh-Token: Fordern Sie ein neues an, wenn es abläuft.

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

Organisationszugriff für Backups

Es gibt zwei Wege. Ein Inhaber oder Admin einer Organisation gibt Ihre App für die geteilten Dateien der Organisation frei, und Ihr Server erhält dann Tokens ohne eine Person (am besten für unbeaufsichtigte Backups). Oder eine Person erlaubt Ihrer App den Scope files.read, und Ihre App liest die eigenen Dateien dieser Person.

Eine Organisation, die Ihre App nicht freigegeben hat, eine, die die Freigabe widerrufen hat, und eine, die nicht existiert, antworten alle mit invalid_grant. Die Admins sehen, wann Ihre App zuletzt verwendet wurde und jede Datei, die sie heruntergeladen hat, und können ihre Ordner jederzeit ändern oder sie widerrufen. Eine widerrufene Freigabe endet mit der nächsten Anfrage: Bereits ausgestellte Tokens funktionieren sofort nicht mehr, ebenso bereits ausgegebene Download-Links. Die eigenen Dateien der Mitglieder gehören nie zur Freigabe einer Organisation.

Die eigenen Dateien einer Person

Fordern Sie openid files.read an (und offline_access für ein Refresh-Token), im üblichen Authorization-Code-Flow mit PKCE. Die Person sieht auf dem Zustimmungsbildschirm, dass Ihre App ihre Dateien sehen und herunterladen darf. Das Token erreicht ihre eigenen Dateien und die geteilten Dateien einer Organisation nur, wenn diese Organisation Ihre App ebenfalls freigegeben hat und die Person ein Mitglied ist, das sie öffnen darf, mit denselben Ordnern. Entfernt die Person Ihre App unter Verbundene Apps, enden die Tokens.

Referenz

Basis-URL https://suite.dazr.eu/api/files/v1. Jeder Endpunkt ist GET (und HEAD); jede andere Methode antwortet 405. Fehler sind JSON: { "error": { "code", "message" } }. Listen nehmen limit (1 bis 1000, Standard 200) und liefern next_cursor, solange es mehr gibt.

Jede Anfrage braucht den Scope files.read. Abfrageparameter:

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

Folgen Sie der Weiterleitung (curl -L): Der Link auf files.dazr.eu braucht keinen Authorization-Header. Eine Datei, die noch nicht im Files-Gateway liegt, wird direkt gestreamt statt weitergeleitet.

Prüfsummen: Dazr Files speichert keinen Hash des Inhalts jeder Datei, daher ist sha256 immer null. Das etag ändert sich, sobald sich der Inhalt ändert (eine neue Version). Berechnen Sie beim Herunterladen selbst einen Hash, wenn Sie einen brauchen. Dateien werden verschlüsselt gespeichert (AES-256-GCM, mit einem Schlüssel pro Bereich, den Dazr verwaltet), und Dazr entschlüsselt sie, wenn Sie sie über TLS herunterladen. Das ist keine Ende-zu-Ende-Verschlüsselung.

Inkrementelle Backups

Rufen Sie changes einmal ohne Cursor auf: Jeder Ordner und jede Datei kommt als created zurück, mit einem cursor. Bewahren Sie den Cursor auf und senden Sie ihn beim nächsten Mal als cursor=. Sie erhalten, was sich seitdem geändert hat: created, updated (neuer Inhalt), moved (umbenannt oder in einen anderen Ordner verschoben), trashed, restored und deleted (endgültig weg oder nicht mehr in den Ordnern, die Ihre App lesen darf). Jede Änderung hat die id, den item_type und das aktuelle item (null bei gelöscht). Ordner kommen vor Dateien, übergeordnete vor ihren Inhalten. Solange has_more true ist, rufen Sie erneut mit dem neuen Cursor auf. Hat sich nichts geändert, erhalten Sie denselben Cursor zurück. Ein Cursor gilt 90 Tage, nur für Ihre App und diesen Bereich; ein abgelaufener antwortet 410, und Sie beginnen ohne Cursor von vorn. Nur die 5 neuesten Cursor Ihrer App je Bereich bleiben gültig.

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 }

Fehler und Grenzen

Fehler haben einen HTTP-Status und einen Body wie { "error": { "code": "not_found", "message": "..." } }. Alles, was Ihr Token nicht erreicht, antwortet 404, genau wie etwas, das nicht existiert.

Der Token-Endpunkt antwortet mit OAuth-Fehlern: invalid_client (falsche Client-ID oder falsches Secret, oder eine App ohne Client-Secret), unauthorized_client (die Dazr Files API ist für Ihre App nicht aktiviert), invalid_scope und invalid_grant (keine Freigabe durch diese Organisation oder nicht aus deren angegebenen Netzwerken).

Jeder Download wird für die Admins der Organisation mit dem Namen Ihrer App, der Datei, der Uhrzeit und einem Teil der IP-Adresse protokolliert: die letzten 5.000, bis zu 180 Tage. Dieselbe Datei, die innerhalb von 10 Minuten erneut heruntergeladen wird, zählt einmal. Die Files-Aktivität der Organisation zeigt eine Zeile pro Tag für Ihre App. Downloads aus den eigenen Dateien einer Person erscheinen bei deren Verbundenen Apps.

WebDAV

Für Backup-Tools, die WebDAV sprechen, erstellt ein Admin der Organisation unter Verbundene Apps für Files eine WebDAV-Anmeldung für Ihre App. Das Passwort wird einmal angezeigt, nur als Hash gespeichert und ist nie das Dazr-Passwort einer Person. Die Anmeldung folgt der Freigabe: dieselben Ordner, Netzwerke und Limits, und sie endet, wenn die Freigabe widerrufen wird.

Ordner- und Dateinamen werden so angezeigt, wie sie in Dazr Files heißen. Haben zwei Elemente in einem Ordner denselben Namen (ohne Rücksicht auf Groß- und Kleinschreibung), behält das ältere ihn, und die anderen erhalten ihre id in Klammern vor der Endung, damit jedes Element einen eigenen Pfad hat. Ein Ordner mit mehr als 10.000 Elementen kann über WebDAV nicht aufgelistet werden; verwenden Sie dafür die API. Nach 10 fehlgeschlagenen Anmeldungen von einer IP-Adresse innerhalb von 15 Minuten wartet diese Adresse 15 Minuten.

rclone

1. Führen Sie rclone config aus, wählen Sie n für einen neuen Remote, nennen Sie ihn dazr und wählen Sie den Speichertyp webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: der Benutzername (dzw_…). Password: Wählen Sie, es selbst einzugeben, und fügen Sie das Passwort ein.
3. Lassen Sie das Bearer-Token leer und speichern Sie. Prüfen Sie mit rclone lsd dazr: und sichern Sie dann.

# ~/.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 vergleicht Größe und Änderungszeit. Verwenden Sie copy statt sync, um Dateien im Backup zu behalten, die in Dazr Files gelöscht wurden.

Synology Cloud Sync

1. Öffnen Sie Cloud Sync auf dem NAS, fügen Sie einen Cloud-Anbieter hinzu und wählen Sie WebDAV.
2. Serveradresse: https://files.dazr.eu/dav/. Benutzername und Passwort: die WebDAV-Anmeldung vom Admin.
3. Wählen Sie einen lokalen Ordner, den Remote-Ordner / (oder einen Ordner) und die Synchronisierungsrichtung Download remote changes only.

Cloud Sync mit WebDAV, Synchronisierungsrichtung „Download remote changes only“. Hyper Backup schreibt Backups auf WebDAV, kann aber nicht davon lesen.