Dazr Files-API: dokumentasjon for utviklere

Les filer fra Dazr Files i din egen programvare, for eksempel for sikkerhetskopi: et REST-API med endringsfeed og WebDAV for sikkerhetskopieringsverktøy. Bare lesing.

• Hurtigstart
• Organisasjonstilgang
• En persons egne filer
• Referanse
• Inkrementelle sikkerhetskopier
• Feil og begrensninger
• WebDAV

Hurtigstart

1. Registrer appen og slå på Dazr Files-API. Registrer appen, eller bruk en du har, i Dazr Identity-konsollen: samme sted som for Logg på med Dazr Identity og Dazr Sign API, med samme klient-ID og hemmelighet. Velg Slå på Dazr Files-API på appens side. For automatiske sikkerhetskopier må det være en webserverapp (med en klienthemmelighet).
2. Bli godkjent. Gi organisasjonen klient-ID-en din. En eier eller administrator åpner Dazr Identity → Organisasjoner → organisasjonen → Tilkoblede apper for Files, skriver inn klient-ID-en og velger hva appen din får lese: alle delte filer eller valgte mapper med alt i dem. De kan også begrense appen til oppgitte nettverk (IP-områder).
3. Hent et token. Serveren din ber om en token med grant_type=client_credentials, organisasjonens id som org, og klient-ID-en og hemmeligheten din (HTTP Basic eller skjemaets body). Bare apper med en klienthemmelighet kan gjøre dette.
4. Kall API-et. Send tilgangstokenet som Authorization: Bearer. Det varer i 10 minutter, og det finnes ingen refresh-token: be om et nytt når det utløper.

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

Organisasjonstilgang for sikkerhetskopi

Det finnes to veier inn. En eier eller administrator i en organisasjon godkjenner appen din for organisasjonens delte filer, og serveren din får da tokener uten en person (best for automatiske sikkerhetskopier). Eller en person gir appen tillatelse med scopet files.read, og appen leser personens egne filer.

En organisasjon som ikke har godkjent appen din, en som har tilbakekalt den, og en som ikke finnes, svarer alle invalid_grant. Administratorene ser når appen sist ble brukt og hver fil den har lastet ned, og kan når som helst endre mappene eller tilbakekalle den. En tilbakekalt godkjenning stopper ved neste forespørsel: tokener som allerede er utstedt, slutter å virke med en gang, og det samme gjør nedlastingslenker som allerede er delt ut. Medlemmenes egne filer er aldri en del av en organisasjons godkjenning.

En persons egne filer

Be om openid files.read (og offline_access for en refresh-token) i den vanlige authorization code-flyten med PKCE. Personen ser på samtykkeskjermen at appen din kan se og laste ned filene. Tokenet når personens egne filer, og en organisasjons delte filer bare når organisasjonen også har godkjent appen din og personen er et medlem som kan åpne dem, med de samme mappene. Når personen fjerner appen under Tilkoblede apper, slutter tokenene å virke.

Referanse

Basis-URL https://suite.dazr.eu/api/files/v1. Alle endepunkter er GET (og HEAD); alle andre metoder svarer 405. Feil er JSON: { "error": { "code", "message" } }. Lister tar limit (1 til 1000, standard 200) og returnerer next_cursor så lenge det finnes mer.

Hver forespørsel krever scopet files.read. Spørreparametere:

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

Følg omdirigeringen (curl -L): lenken på files.dazr.eu trenger ingen Authorization-header. En fil som ennå ikke ligger i Files-gatewayen, strømmes direkte i stedet for å omdirigeres.

Sjekksummer: Dazr Files lagrer ikke en hash av innholdet i hver fil, så sha256 er alltid null. etag endres hver gang innholdet endres (en ny versjon). Regn ut din egen hash under nedlastingen hvis du trenger en. Filer lagres kryptert (AES-256-GCM, med en nøkkel per område som Dazr forvalter), og Dazr dekrypterer dem når du laster dem ned over TLS. Dette er ikke ende-til-ende-kryptering.

Inkrementelle sikkerhetskopier

Kall changes én gang uten cursor: alle mapper og filer kommer tilbake som created, med en cursor. Ta vare på cursoren og send den neste gang som cursor=. Du får det som er endret siden: created, updated (nytt innhold), moved (gitt nytt navn eller flyttet til en annen mappe), trashed, restored og deleted (borte for godt, eller ikke lenger i mappene appen får lese). Hver endring har id, item_type og gjeldende item (null når slettet). Mapper kommer før filer, foreldre før barna sine. Så lenge has_more er true, kaller du igjen med den nye cursoren. Hvis ingenting er endret, får du samme cursor tilbake. En cursor virker i 90 dager, bare for appen din og det området; en utløpt svarer 410, og du begynner på nytt uten cursor. Bare appens 5 nyeste cursorer for et område forblir gyldige.

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 }

Feil og begrensninger

Feil har en HTTP-status og en body som { "error": { "code": "not_found", "message": "..." } }. Alt tokenet ikke når, svarer 404, akkurat som noe som ikke finnes.

Token-endepunktet svarer med OAuth-feil: invalid_client (feil klient-ID eller hemmelighet, eller en app uten klienthemmelighet), unauthorized_client (Dazr Files-API er ikke slått på for appen), invalid_scope og invalid_grant (ingen godkjenning fra organisasjonen, eller ikke fra de oppgitte nettverkene).

Hver nedlasting logges for organisasjonens administratorer med appens navn, filen, tidspunktet og en del av IP-adressen: de siste 5 000, i opptil 180 dager. Samme fil lastet ned igjen innen 10 minutter teller én gang. Organisasjonens Files-aktivitet viser én linje per dag for appen din. Nedlastinger fra en persons egne filer vises under personens Tilkoblede apper.

WebDAV

For sikkerhetskopieringsverktøy som bruker WebDAV, oppretter en administrator i organisasjonen en WebDAV-pålogging for appen din under Tilkoblede apper for Files. Passordet vises én gang, lagres bare som hash og er aldri noens Dazr-passord. Påloggingen følger godkjenningen: samme mapper, nettverk og grenser, og den stopper når godkjenningen tilbakekalles.

Mappe- og filnavn vises slik de er i Dazr Files. Når to elementer i en mappe har samme navn (uten hensyn til store og små bokstaver), beholder det eldste navnet, og de andre får sin id i parentes før filendelsen, slik at hvert element har sin egen sti. En mappe med over 10 000 elementer kan ikke vises over WebDAV; bruk API-et for den. Etter 10 mislykkede pålogginger fra én IP-adresse innen 15 minutter må den adressen vente i 15 minutter.

rclone

1. Kjør rclone config, velg n for en ny remote, kall den dazr og velg lagringstypen webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: brukernavnet (dzw_…). Password: velg å skrive det selv, og lim inn passordet.
3. La bearer token stå tom og lagre. Sjekk med rclone lsd dazr:, og ta så sikkerhetskopi.

# ~/.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 sammenligner størrelse og endringstid. Bruk copy i stedet for sync for å beholde filer i sikkerhetskopien som er slettet i Dazr Files.

Synology Cloud Sync

1. Åpne Cloud Sync på NAS-en, legg til en skyleverandør og velg WebDAV.
2. Serveradresse: https://files.dazr.eu/dav/. Brukernavn og passord: WebDAV-påloggingen fra administratoren.
3. Velg en lokal mappe, den eksterne mappen / (eller én mappe) og synkroniseringsretningen Download remote changes only.

Cloud Sync med WebDAV, synkroniseringsretning «Download remote changes only». Hyper Backup skriver sikkerhetskopier til WebDAV, men kan ikke lese derfra.