Dazr Files API: dokumentacja dla deweloperów

Czytaj pliki z Dazr Files we własnym oprogramowaniu, na przykład do kopii zapasowych: REST API z kanałem zmian oraz WebDAV dla narzędzi do kopii. Tylko odczyt.

• Szybki start
• Dostęp organizacji
• Własne pliki osoby
• Dokumentacja
• Przyrostowe kopie zapasowe
• Błędy i limity
• WebDAV

Szybki start

1. Zarejestruj aplikację i włącz Dazr Files API. Zarejestruj aplikację albo użyj istniejącej w konsoli Dazr Identity: w tym samym miejscu co logowanie przez Dazr Identity i Dazr Sign API, z tym samym identyfikatorem klienta i sekretem. Na stronie aplikacji wybierz Włącz Dazr Files API. Do automatycznych kopii zapasowych aplikacja musi być serwerowa (z sekretem klienta).
2. Uzyskaj zatwierdzenie. Przekaż organizacji swój identyfikator klienta. Właściciel lub administrator otwiera Dazr Identity → Organizacje → organizacja → Połączone aplikacje w Files, wpisuje identyfikator klienta i wybiera, co aplikacja może czytać: wszystkie udostępnione pliki albo wybrane foldery z całą zawartością. Może też ograniczyć aplikację do podanych sieci (zakresów IP).
3. Pobierz token. Twój serwer prosi o token z grant_type=client_credentials, id organizacji jako org oraz identyfikatorem klienta i sekretem (HTTP Basic lub treść formularza). Mogą to robić tylko aplikacje z sekretem klienta.
4. Wywołaj API. Wysyłaj token dostępu jako Authorization: Bearer. Jest ważny 10 minut i nie ma tokenu odświeżania: poproś o nowy, gdy wygaśnie.

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

Dostęp organizacji do kopii zapasowych

Są dwie drogi. Właściciel lub administrator organizacji zatwierdza twoją aplikację dla udostępnionych plików organizacji, a twój serwer dostaje tokeny bez udziału osoby (najlepsze do automatycznych kopii zapasowych). Albo osoba zezwala aplikacji na scope files.read, a aplikacja czyta własne pliki tej osoby.

Organizacja, która nie zatwierdziła twojej aplikacji, taka, która ją odwołała, i taka, która nie istnieje, odpowiadają tak samo: invalid_grant. Administratorzy widzą, kiedy aplikacja była ostatnio używana, i każdy pobrany przez nią plik, a w każdej chwili mogą zmienić jej foldery lub ją odwołać. Odwołane zatwierdzenie przestaje działać przy następnym żądaniu: wydane już tokeny od razu przestają działać, podobnie jak przekazane linki do pobrania. Własne pliki członków nigdy nie są objęte zatwierdzeniem organizacji.

Własne pliki osoby

Poproś o openid files.read (oraz offline_access dla tokenu odświeżania) w zwykłym przepływie authorization code z PKCE. Osoba widzi na ekranie zgody, że aplikacja może przeglądać i pobierać jej pliki. Token sięga do jej własnych plików, a do udostępnionych plików organizacji tylko wtedy, gdy ta organizacja też zatwierdziła aplikację, a osoba jest członkiem, który może je otwierać, z tymi samymi folderami. Gdy osoba usunie aplikację w Połączonych aplikacjach, tokeny przestaną działać.

Dokumentacja

Bazowy URL https://suite.dazr.eu/api/files/v1. Każdy endpoint to GET (i HEAD); każda inna metoda odpowiada 405. Błędy są w JSON: { "error": { "code", "message" } }. Listy przyjmują limit (od 1 do 1000, domyślnie 200) i zwracają next_cursor, dopóki jest więcej.

Każde żądanie wymaga scope files.read. Parametry zapytania:

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

Podążaj za przekierowaniem (curl -L): link na files.dazr.eu nie wymaga nagłówka Authorization. Plik, którego nie ma jeszcze w bramie Files, jest przesyłany bezpośrednio zamiast przekierowania.

Sumy kontrolne: Dazr Files nie przechowuje skrótu zawartości każdego pliku, więc sha256 ma zawsze wartość null. etag zmienia się za każdym razem, gdy zmienia się zawartość (nowa wersja). Jeśli potrzebujesz skrótu, oblicz go sam podczas pobierania. Pliki są przechowywane w postaci zaszyfrowanej (AES-256-GCM, z kluczem dla każdej przestrzeni, który przechowuje Dazr), a Dazr odszyfrowuje je, gdy pobierasz je przez TLS. To nie jest szyfrowanie end-to-end.

Przyrostowe kopie zapasowe

Wywołaj changes raz bez kursora: każdy folder i plik wraca jako created, z cursor. Zachowaj kursor i następnym razem wyślij go jako cursor=. Dostaniesz to, co zmieniło się od tego czasu: created, updated (nowa zawartość), moved (zmieniona nazwa lub przeniesienie do innego folderu), trashed, restored i deleted (usunięte na stałe albo już poza folderami, które aplikacja może czytać). Każda zmiana ma id, item_type i bieżący item (null po usunięciu). Foldery są przed plikami, rodzice przed dziećmi. Dopóki has_more ma wartość true, wywołuj ponownie z nowym kursorem. Gdy nic się nie zmieniło, dostajesz ten sam kursor. Kursor działa 90 dni, tylko dla twojej aplikacji i tej przestrzeni; wygasły odpowiada 410 i zaczynasz od nowa bez kursora. Ważnych pozostaje tylko 5 najnowszych kursorów aplikacji dla danej przestrzeni.

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 }

Błędy i limity

Błędy mają status HTTP i treść w rodzaju { "error": { "code": "not_found", "message": "..." } }. Wszystko, do czego token nie sięga, odpowiada 404, tak samo jak to, co nie istnieje.

Endpoint tokenu odpowiada błędami OAuth: invalid_client (błędny identyfikator klienta lub sekret albo aplikacja bez sekretu klienta), unauthorized_client (Dazr Files API nie jest włączone dla aplikacji), invalid_scope oraz invalid_grant (brak zatwierdzenia tej organizacji lub żądanie spoza jej sieci).

Każde pobranie jest rejestrowane dla administratorów organizacji z nazwą aplikacji, plikiem, czasem i częścią adresu IP: ostatnie 5000, do 180 dni. Ten sam plik pobrany ponownie w ciągu 10 minut liczy się raz. Aktywność Files organizacji pokazuje jeden wiersz dziennie dla twojej aplikacji. Pobrania z własnych plików osoby widać w jej Połączonych aplikacjach.

WebDAV

Dla narzędzi do kopii zapasowych obsługujących WebDAV administrator organizacji tworzy login WebDAV dla twojej aplikacji w sekcji Połączone aplikacje w Files. Hasło jest pokazywane raz, przechowywane tylko jako skrót i nigdy nie jest czyimś hasłem do Dazr. Login podąża za zatwierdzeniem: te same foldery, sieci i limity, i przestaje działać, gdy zatwierdzenie zostanie odwołane.

Nazwy folderów i plików są pokazywane tak, jak w Dazr Files. Gdy dwa elementy w folderze mają tę samą nazwę (bez rozróżniania wielkości liter), starszy ją zachowuje, a pozostałe dostają swoje id w nawiasie przed rozszerzeniem, więc każdy element ma własną ścieżkę. Folderu z ponad 10 000 elementów nie można wyświetlić przez WebDAV; użyj do niego API. Po 10 nieudanych logowaniach z jednego adresu IP w ciągu 15 minut ten adres czeka 15 minut.

rclone

1. Uruchom rclone config, wybierz n (nowy remote), nazwij go dazr i wybierz typ magazynu webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: nazwa użytkownika (dzw_…). Password: wybierz wpisanie własnego i wklej hasło.
3. Zostaw pusty bearer token i zapisz. Sprawdź poleceniem rclone lsd dazr:, a potem rób kopię.

# ~/.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 porównuje rozmiar i czas modyfikacji. Użyj copy zamiast sync, aby zachować w kopii pliki usunięte w Dazr Files.

Synology Cloud Sync

1. Otwórz Cloud Sync na NAS, dodaj dostawcę chmury i wybierz WebDAV.
2. Adres serwera: https://files.dazr.eu/dav/. Nazwa użytkownika i hasło: login WebDAV od administratora.
3. Wybierz folder lokalny, folder zdalny / (lub jeden folder) i kierunek synchronizacji Download remote changes only.

Cloud Sync z WebDAV, kierunek synchronizacji „Download remote changes only”. Hyper Backup zapisuje kopie na WebDAV, ale nie może z niego czytać.