Berechtigungen (Scopes)
Beim Anlegen wählen Sie, was ein Token darf. Sie können nur Berechtigungen vergeben, die Sie selbst in der Verwaltung haben.
| Scope | Erlaubt | Der Ersteller braucht |
|---|---|---|
locations:read | Garagenparks lesen | Standorte (Lesen) |
occupancy:read | Vermietungsquote lesen (aktuell, Verlauf, je Garagentyp) | Belegungsplan (Lesen) |
tenants:read | Mieter lesen (ohne Bankdaten) | Mieter (Lesen), Vermietungsprozess (Lesen) |
tenants:import | Bestandsmieter an den Import übergeben | Datenimport (Bearbeiten), Vermietungsprozess (Lesen) |
tenants:import_commit | Importierte Bestandsmieter übernehmen (legt Mieter und Verträge an) | Datenimport (Bearbeiten), Vermietungsprozess (Bearbeiten) |
bookings:read | Buchungsjournal und Umsatz lesen | Buchhaltung Übersicht (Lesen) |
open_items:read | Offene Posten lesen | Forderungen (Lesen) |
dunning:read | Mahnstand und ausgestellte Mahnungen lesen | Forderungen (Lesen) |
invoices:read | Rechnungen lesen | Rechnungen (Lesen) |
payments:read | Zahlungseingänge lesen (ohne Bankdaten) | Zahlungen (Lesen), Buchhaltung Übersicht (Lesen) |
payments:read_counterparty | Zusatz zu payments:read: Bankdaten und Verwendungszweck der Zahlenden | Zahlungen (Lesen), Buchhaltung Übersicht (Lesen) |
emails:read | Versendete E-Mails lesen (Betreff, Status, Vorschau) | E-Mail-Protokoll (Lesen), Mieter (Lesen) |
emails:read_body | Zusatz zu emails:read: Volltext der E-Mails | E-Mail-Protokoll (Lesen), Mieter (Lesen) |
usage:read | Zugriffsprotokoll der eigenen API-Abrufe lesen | API-Zugang (Lesen) |
documents:read | Dokumente lesen (Mieter- und Standortdokumente, nur Angaben zur Datei) | Mieter (Lesen), Standorte (Lesen) |
documents:download | Zusatz zu documents:read: kurzlebige Download-Links für Dokumente | Mieter (Lesen), Standorte (Lesen) |
contractors:read | Handwerksbetriebe und Aufträge lesen | Artikel und Handwerker (Lesen), Garagen/Einheiten (Lesen), Vermietungsprozess (Lesen) |
units:read | Einheiten und Garagen lesen | Garagen/Einheiten (Lesen), Standorte (Lesen) |
contracts:read | Verträge, Nachträge und Kündigungen lesen | Vermietungsprozess (Lesen), Mieter (Lesen) |
datev:export | DATEV-Exporte abrufen und anstoßen | Finanzbuchhaltung (Lesen) |
prospects:read | Interessenten und Warteliste lesen | Vermietungsprozess (Lesen) |
prospects:write | Zusatz zu prospects:read: Interessentenanfragen einliefern | Vermietungsprozess (Bearbeiten) |
appointments:read | Termine lesen | Kalender (Lesen) |
appointments:write | Zusatz zu appointments:read: Termine anlegen | Kalender (Bearbeiten) |
damages:read | Schäden lesen | Garagen/Einheiten (Lesen), Vermietungsprozess (Lesen) |
damages:write | Zusatz zu damages:read: Schäden anlegen und Status setzen | Garagen/Einheiten (Bearbeiten), Vermietungsprozess (Bearbeiten) |
utility:read | Nebenkostenabrechnungen, Zähler und Zählerstände lesen | Zählerstände (Lesen), Strom (Lesen), Wasser (Lesen) |
utility:write | Zusatz zu utility:read: Zählerstände eintragen | Zählerstände (Bearbeiten), Strom (Bearbeiten), Wasser (Bearbeiten) |
webhooks:manage | Webhooks einrichten und verwalten | API-Zugang (Vollzugriff) |
timeline:read | Mieter-Zeitleiste lesen (nur Ereignisse, für die das Token auch das Leserecht hat) | Mieter (Lesen) |
Zusatzrechte: Einige Scopes erweitern einen anderen und berechtigen allein zu nichts: payments:read_counterparty (Bankdaten der Zahlenden), documents:download (Download-Links), emails:read_body (Volltext der E-Mails) sowie die Schreibrechte utility:write (Zählerstände), damages:write (Schäden), appointments:write (Termine) und prospects:write (Interessenten). Das Token braucht jeweils auch den Grund-Scope (…:read). Ein Token darf bis zu 40 Scopes tragen. Es sieht immer die ganze Organisation — Beschränkungen auf einzelne Standorte gibt es am Token nicht.
Fehlt einem Token der passende Scope, antwortet die API mit 403 insufficient_scope und nennt den benötigten Scope im Feld error.required_scope.
Die Rechte des Erstellers werden bei jedem Aufruf neu geprüft. Verliert die Person, die das Token angelegt hat, ein nötiges Recht — auch das Recht API-Zugang selbst —, antwortet die API sofort mit 403 insufficient_permissions. Bekommt sie das Recht zurück, funktioniert das Token wieder.