← Alle Artikel
Entwickler

REST-API für Integrationen

Die gesamte App per API nutzen: Tokens, Limits, Fehler und alle Endpunkte.

Alles, was die Web-App kann, geht auch per REST-API – für eigene Programme, Skripte und Integrationen. Die API läuft auf derselben Plattform wie die App und ist unter api.everhold.io erreichbar (Basis-Adresse https://api.everhold.io/v1). Das S3-Gateway (Speicher-API) hat einen eigenen Hostnamen: s3.everhold.io.

Zero-Knowledge gilt auch hier: Die API liefert und akzeptiert nur Ciphertext. Ver- und Entschlüsseln passiert in deinem Programm mit dem Master-Key deines Kontos (Passphrase → Argon2id → Schlüssel-Hülle aus GET /account). Ein Token gibt nie Klartext frei. Als Referenz dient das Backup-Programm (cli/everhold.ts) – es nutzt genau diese API.

Token erstellen

  1. In der App: „Konto & Sicherheit → API-Zugang“ öffnen.
  2. Bezeichnung, Berechtigung (nur lesen oder lesen und schreiben) und Laufzeit wählen und mit der Passphrase bestätigen.
  3. Token kopieren – es wird nur einmal angezeigt. Gespeichert wird nur ein Hash.
curl https://api.everhold.io/v1/account \
  -H "Authorization: Bearer evh_…"

Limits

Jedes Token hat ein eigenes Limit pro Minute: Free 60, Pro 300, Team 1200 Anfragen. Zusätzlich gilt pro IP-Adresse eine Obergrenze von 600 lesenden und 120 schreibenden Anfragen pro Minute. Anmeldung, Registrierung und Wiederherstellung sind noch enger begrenzt. Bei Überschreitung antwortet die API mit 429, dem Header Retry-After (Sekunden) und den Headern RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset.

Fehler

Fehler sind JSON: { "error": { "code", "message", "details" } }.

StatusCodeBedeutung
400BAD_REQUESTUngültige Anfrage
401UNAUTHENTICATEDToken fehlt, ist ungültig, abgelaufen oder widerrufen
403FORBIDDENBerechtigung fehlt (z. B. Token nur lesend) oder Aufruf nur in der App
402PLAN_REQUIRED / QUOTA_EXCEEDEDPaket oder Speicher reicht nicht
404NOT_FOUNDNicht vorhanden oder kein Zugriff
409VERSION_CONFLICTIndex wurde zwischenzeitlich geändert – neu laden und erneut schreiben
409SLOTS_FULL / TEAM_LIMITKein freier Platz im Team bzw. zu viele Teams für dein Paket
423TEAM_PAUSEDDas Team ist pausiert, bis der Inhaber wieder bezahlt
423CLOUD_LOCKED„Meine Cloud“ ist gesperrt, bis die Daten wieder ins Paket passen – Löschen geht
429RATE_LIMITEDZu viele Anfragen – nach Retry-After erneut versuchen

Nur in der App

Aus Sicherheitsgründen nicht per Token möglich: Anmeldung und Registrierung, Passphrase, Passkeys, Recovery-Kit und Sitzungen, Token-Verwaltung, Abrechnung, Plätze und Guthaben, Admin, Team beitreten, übernehmen und löschen, SSO, Firmen-Notfallzugriff und das Löschen des Kontos.

Dateien hoch- und herunterladen

  1. POST /objects mit den Größen der verschlüsselten Teile – die Antwort enthält vorsignierte Upload-URLs.
  2. Jedes Teil per PUT an seine URL senden (Format „frame2“, siehe cli/core.ts).
  3. POST /objects/{id}/complete.
  4. Dateiname, Datei-Schlüssel (mit dem Master-Key verpackt) und Teile-Metadaten in den verschlüsselten Index schreiben: PUT /vault/index mit baseVersion.

.env-Dateien in geteilten Tresoren

Im verschlüsselten Index eines geteilten Tresors liegen .env-Einträge als Einträge vom Typ „env“: { kind: "env", title: <Projekt>, environment: "production" | "preview" | …, vars: [{ key, value }] }. So lassen sich Umgebungsvariablen aus CI/CD lesen und schreiben (GET /vaults, PUT /vaults/{id}/index) – verschlüsselt mit dem Tresor-Schlüssel, den dein Konto per ECDH-Hülle erhält.

OpenAPI

Maschinenlesbare Beschreibung: https://api.everhold.io/v1/openapi.json (OpenAPI 3.1) – importierbar in Postman, Insomnia oder Generatoren für Client-Bibliotheken.

Endpunkte

Konto

AufrufBeschreibung
GET /accountKontoübersicht: Paket, Speicher, Schlüssel-Hüllen (für den Master-Key), Passkeys, Teams

Dateien (Objekte)

AufrufBeschreibung
POST /objectsUpload starten: Teile (Pieces) anmelden, Antwort enthält vorsignierte Upload-URLs — { fmt: "frame2", teamId?: string | null, pieces: [{ index, cipherBytes }] }
POST /objects/{id}/urlsAbgelaufene Upload-URLs für einzelne Teile erneuern — { pieces: number[] }
POST /objects/{id}/completeUpload abschließen (prüft Größen, bucht Speicher ab)
GET /objects/{id}/downloadVorsignierte Download-URLs der verschlüsselten Teile
DELETE /objects/{id}Objekt endgültig löschen
POST /objects/{id}/trashIn den Papierkorb verschieben (Abos)
POST /objects/{id}/restoreAus dem Papierkorb wiederherstellen
POST /objects/{id}/versionAktuelle Fassung als Version behalten (Abos)
POST /objects/{id}/promoteÄltere Version zur aktuellen machen
POST /objects/{id}/moveDatei verschieben: Meine Cloud ↔ Teamordner, Team → Team — { teamId: string | null }
GET /objects/{id}/proofFilecoin-Speichernachweis (Zertifikat) einer Datei
GET /objects/trashObjekte im Papierkorb
GET /objects/versionsAufbewahrte Versionen
GET /objects/filecoinFilecoin-Status aller Objekte
POST /objects/statusWelche dieser Objekte es noch gibt (Abgleich des Index), höchstens 5000 IDs — { ids: string[] }

Verschlüsselter Index

AufrufBeschreibung
GET /vault/indexVerschlüsselten Tresor-Index lesen (Dateinamen, Schlüssel, Einträge – nur Ciphertext)
PUT /vault/indexIndex schreiben (optimistisch: baseVersion muss stimmen, sonst 409) — { baseVersion: number, body: base64 }

Secure-Send-Links

AufrufBeschreibung
GET /sharesEigene Secure-Send-Links
POST /sharesLink anlegen (verschlüsselte Metadaten, Ablauf, Download-Limit) — { objectId | objectIds, meta, expiresInHours, maxDownloads }
DELETE /shares/{id}Link widerrufen

Geteilte Tresore (inkl. .env)

AufrufBeschreibung
GET /vaultsGeteilte Tresore eines Teams (?team={id}), ohne Team die eigenen: Übersicht, eigene Rolle, Mitglieder, verpackte Schlüssel, verschlüsselter Index
POST /vaultsTresor anlegen (im Team ab Rolle „edit“, ohne teamId als eigener Tresor) — { id, wrapped, body, teamId? }
PUT /vaults/{id}/indexIndex (Name, Passwörter, Notizen, 2FA, .env-Einträge) schreiben – Rolle „edit“ nötig — { baseVersion, body }
POST /vaults/{id}/keysSchlüssel an Mitglieder verteilen / neue Generation anlegen – Rolle „manage“ — { generation, grants: [...], rotate? }
POST /vaults/{id}/membersPerson hinzufügen — { accountId, role: "view" | "edit" | "manage" }
PATCH /vaults/{id}/members/{member}Rolle ändern — { role }
DELETE /vaults/{id}/members/{member}Person entfernen oder Tresor verlassen
GET /vaults/{id}/auditProtokoll des Tresors – Rolle „manage“
DELETE /vaults/{id}Tresor löschen – Rolle „manage“

Teams

AufrufBeschreibung
GET /teamsMeine Teams (eigene zuerst, seitenweise über ?cursor), dazu Limits und Plätze
POST /teamsTeam gründen (eigenes Team- oder Enterprise-Abo): ID, Hülle des ersten Ordner-Schlüssels und verschlüsselte Meta (Name, Icon) erzeugt der Client — { id, wrapped, meta: base64 }
GET /teams/{id}Team: Mitglieder mit Rolle und Platz, Richtlinie; ab Rolle „admin“ auch Einladungen und Plätze
PUT /teams/{id}/metaName und Icon (verschlüsselt) ändern – Rolle „admin“ — { baseVersion, meta: base64 }
POST /teams/{id}/invitesEinladungslink erstellen – Rolle „admin“ (Admins lädt nur der Inhaber ein) — { role?: "view" | "edit" | "admin" }
DELETE /teams/{id}/invites/{inviteId}Einladung zurückziehen
PATCH /teams/{id}/members/{accountId}Rolle ändern – Rolle „admin“ (Admin-Rechte vergibt nur der Inhaber) — { role: "view" | "edit" | "admin" }
DELETE /teams/{id}/members/{accountId}Mitglied entfernen oder Team verlassen (eigene ID)
GET /teams/{id}/adminAdmin-Konsole: Rollen, Richtlinien, Speicher, Plätze – Rolle „admin“
GET /teams/{id}/auditTeam-Protokoll (?from, to, member, kind, limit)
GET /teams/{id}/reportCompliance-Bericht (?days)
PUT /teams/{id}/policyTeam-Richtlinien setzen

Teamordner

AufrufBeschreibung
GET /teams/{id}/spaceZustand des Teamordners: eigene Rolle, Schlüssel-Hüllen, Mitglieder, Index-Version
GET /teams/{id}/space/indexVerschlüsselten Ordner-Index lesen (Version im Header X-FV-Version)
PUT /teams/{id}/space/indexOrdner-Index schreiben – Rolle „edit“ (Binärdaten, Basisversion im Header X-FV-Base-Version)
POST /teams/{id}/space/keysOrdner-Schlüssel an Mitglieder verteilen / neue Generation anlegen (Rolle „edit“), höchstens 200 je Aufruf — { generation, grants: [{ accountId, wrapped }] }

Speicher-API (S3-Zugänge)

AufrufBeschreibung
GET /s3Übersicht: Zugangsschlüssel, Buckets, Endpunkt
POST /s3/keysS3-Zugangsschlüssel erzeugen (Secret nur in der Antwort) — { label }
DELETE /s3/keys/{id}S3-Zugangsschlüssel widerrufen
POST /s3/bucketsBucket anlegen (optional mit Object Lock) — { name, objectLock }
PATCH /s3/buckets/{name}Aufbewahrung und Sperre eines Buckets ändern

Sonstiges

AufrufBeschreibung
GET /healthBetriebsstatus (ohne Anmeldung)
GET /statusÖffentlicher Status und Störungen (ohne Anmeldung)
GET /fxWechselkurse für die Preisanzeige
GET /openapi.jsonDieses API als OpenAPI-3.1-Dokument
Nicht gefunden, was du suchst? Support kontaktieren →