← Alle ArtikelEntwickler
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
- In der App: „Konto & Sicherheit → API-Zugang“ öffnen.
- Bezeichnung, Berechtigung (nur lesen oder lesen und schreiben) und Laufzeit wählen und mit der Passphrase bestätigen.
- 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" } }.
| Status | Code | Bedeutung |
|---|
| 400 | BAD_REQUEST | Ungültige Anfrage |
| 401 | UNAUTHENTICATED | Token fehlt, ist ungültig, abgelaufen oder widerrufen |
| 403 | FORBIDDEN | Berechtigung fehlt (z. B. Token nur lesend) oder Aufruf nur in der App |
| 402 | PLAN_REQUIRED / QUOTA_EXCEEDED | Paket oder Speicher reicht nicht |
| 404 | NOT_FOUND | Nicht vorhanden oder kein Zugriff |
| 409 | VERSION_CONFLICT | Index wurde zwischenzeitlich geändert – neu laden und erneut schreiben |
| 409 | SLOTS_FULL / TEAM_LIMIT | Kein freier Platz im Team bzw. zu viele Teams für dein Paket |
| 423 | TEAM_PAUSED | Das Team ist pausiert, bis der Inhaber wieder bezahlt |
| 423 | CLOUD_LOCKED | „Meine Cloud“ ist gesperrt, bis die Daten wieder ins Paket passen – Löschen geht |
| 429 | RATE_LIMITED | Zu 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
- POST /objects mit den Größen der verschlüsselten Teile – die Antwort enthält vorsignierte Upload-URLs.
- Jedes Teil per PUT an seine URL senden (Format „frame2“, siehe cli/core.ts).
- POST /objects/{id}/complete.
- 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
| Aufruf | Beschreibung |
|---|
| GET /account | Kontoübersicht: Paket, Speicher, Schlüssel-Hüllen (für den Master-Key), Passkeys, Teams |
Dateien (Objekte)
| Aufruf | Beschreibung |
|---|
| POST /objects | Upload starten: Teile (Pieces) anmelden, Antwort enthält vorsignierte Upload-URLs — { fmt: "frame2", teamId?: string | null, pieces: [{ index, cipherBytes }] } |
| POST /objects/{id}/urls | Abgelaufene Upload-URLs für einzelne Teile erneuern — { pieces: number[] } |
| POST /objects/{id}/complete | Upload abschließen (prüft Größen, bucht Speicher ab) |
| GET /objects/{id}/download | Vorsignierte Download-URLs der verschlüsselten Teile |
| DELETE /objects/{id} | Objekt endgültig löschen |
| POST /objects/{id}/trash | In den Papierkorb verschieben (Abos) |
| POST /objects/{id}/restore | Aus dem Papierkorb wiederherstellen |
| POST /objects/{id}/version | Aktuelle Fassung als Version behalten (Abos) |
| POST /objects/{id}/promote | Ältere Version zur aktuellen machen |
| POST /objects/{id}/move | Datei verschieben: Meine Cloud ↔ Teamordner, Team → Team — { teamId: string | null } |
| GET /objects/{id}/proof | Filecoin-Speichernachweis (Zertifikat) einer Datei |
| GET /objects/trash | Objekte im Papierkorb |
| GET /objects/versions | Aufbewahrte Versionen |
| GET /objects/filecoin | Filecoin-Status aller Objekte |
| POST /objects/status | Welche dieser Objekte es noch gibt (Abgleich des Index), höchstens 5000 IDs — { ids: string[] } |
Verschlüsselter Index
| Aufruf | Beschreibung |
|---|
| GET /vault/index | Verschlüsselten Tresor-Index lesen (Dateinamen, Schlüssel, Einträge – nur Ciphertext) |
| PUT /vault/index | Index schreiben (optimistisch: baseVersion muss stimmen, sonst 409) — { baseVersion: number, body: base64 } |
Secure-Send-Links
| Aufruf | Beschreibung |
|---|
| GET /shares | Eigene Secure-Send-Links |
| POST /shares | Link anlegen (verschlüsselte Metadaten, Ablauf, Download-Limit) — { objectId | objectIds, meta, expiresInHours, maxDownloads } |
| DELETE /shares/{id} | Link widerrufen |
Geteilte Tresore (inkl. .env)
| Aufruf | Beschreibung |
|---|
| GET /vaults | Geteilte Tresore eines Teams (?team={id}), ohne Team die eigenen: Übersicht, eigene Rolle, Mitglieder, verpackte Schlüssel, verschlüsselter Index |
| POST /vaults | Tresor anlegen (im Team ab Rolle „edit“, ohne teamId als eigener Tresor) — { id, wrapped, body, teamId? } |
| PUT /vaults/{id}/index | Index (Name, Passwörter, Notizen, 2FA, .env-Einträge) schreiben – Rolle „edit“ nötig — { baseVersion, body } |
| POST /vaults/{id}/keys | Schlüssel an Mitglieder verteilen / neue Generation anlegen – Rolle „manage“ — { generation, grants: [...], rotate? } |
| POST /vaults/{id}/members | Person 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}/audit | Protokoll des Tresors – Rolle „manage“ |
| DELETE /vaults/{id} | Tresor löschen – Rolle „manage“ |
Teams
| Aufruf | Beschreibung |
|---|
| GET /teams | Meine Teams (eigene zuerst, seitenweise über ?cursor), dazu Limits und Plätze |
| POST /teams | Team 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}/meta | Name und Icon (verschlüsselt) ändern – Rolle „admin“ — { baseVersion, meta: base64 } |
| POST /teams/{id}/invites | Einladungslink 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}/admin | Admin-Konsole: Rollen, Richtlinien, Speicher, Plätze – Rolle „admin“ |
| GET /teams/{id}/audit | Team-Protokoll (?from, to, member, kind, limit) |
| GET /teams/{id}/report | Compliance-Bericht (?days) |
| PUT /teams/{id}/policy | Team-Richtlinien setzen |
Teamordner
| Aufruf | Beschreibung |
|---|
| GET /teams/{id}/space | Zustand des Teamordners: eigene Rolle, Schlüssel-Hüllen, Mitglieder, Index-Version |
| GET /teams/{id}/space/index | Verschlüsselten Ordner-Index lesen (Version im Header X-FV-Version) |
| PUT /teams/{id}/space/index | Ordner-Index schreiben – Rolle „edit“ (Binärdaten, Basisversion im Header X-FV-Base-Version) |
| POST /teams/{id}/space/keys | Ordner-Schlüssel an Mitglieder verteilen / neue Generation anlegen (Rolle „edit“), höchstens 200 je Aufruf — { generation, grants: [{ accountId, wrapped }] } |
Speicher-API (S3-Zugänge)
| Aufruf | Beschreibung |
|---|
| GET /s3 | Übersicht: Zugangsschlüssel, Buckets, Endpunkt |
| POST /s3/keys | S3-Zugangsschlüssel erzeugen (Secret nur in der Antwort) — { label } |
| DELETE /s3/keys/{id} | S3-Zugangsschlüssel widerrufen |
| POST /s3/buckets | Bucket anlegen (optional mit Object Lock) — { name, objectLock } |
| PATCH /s3/buckets/{name} | Aufbewahrung und Sperre eines Buckets ändern |
Sonstiges
| Aufruf | Beschreibung |
|---|
| GET /health | Betriebsstatus (ohne Anmeldung) |
| GET /status | Öffentlicher Status und Störungen (ohne Anmeldung) |
| GET /fx | Wechselkurse für die Preisanzeige |
| GET /openapi.json | Dieses API als OpenAPI-3.1-Dokument |