X-API-Key-Header bei jedem Request. Der Key bestimmt, auf welchen Kunden-Scope und welche Datenstufen du zugreifen kannst.
Einen Key erstellen
Trassets richtet den Portal-Zugang für deine Organisation ein; eine öffentliche Registrierung gibt es nicht. Mit diesem Zugang meldet sich ein Administrator deiner Organisation unter portal.api.trassets.ai an und erzeugt API-Keys selbst über das Dashboard. Der Klartext-Key wird genau einmal angezeigt. Kopiere ihn sofort und speichere ihn in einem sicheren Secrets-Manager. Wenn du ihn verlierst, musst du den alten Key widerrufen und einen neuen erzeugen.Den Key in Requests übergeben
Füge denX-API-Key-Header bei jedem Call hinzu. Hier ein minimales curl-Beispiel gegen eine live /v1/-Tabelle:
Key-Typen
Jeder Key hat einen Typ,raw oder transformed. Der Typ entscheidet, ob der Key Raw-Quelltabellen lesen darf. Ein Administrator setzt ihn im Portal; für Kunden angelegte Keys sind transformed.
Ein
raw-Key kann keine Einschränkungen tragen. Zum Lesen einer Raw-Tabelle braucht er zusätzlich beide Grants für personenbezogene Daten, personal und personal_financial, weil sich Raw-Tabellen nicht spaltenweise filtern lassen; /v1/raw/tables listet die Tabellen in jedem Fall. Ein transformed-Key bekommt keine Rohdaten und keine Tabellen ohne Kategorie.
Ist /v1/raw/tables leer, obwohl der Key gültig ist, ist der Key transformed. Liefert eine Raw-Tabelle 403 mit detail “Raw export requires an API key of type raw with personal data grants. Contact your administrator or Trassets support.”, ist der Key transformed oder ihm fehlt einer der beiden Grants — frag deinen Administrator oder den Trassets-Support. Ein geänderter Key-Typ oder Grant wirkt nach etwa einer Minute.
Grants für personenbezogene Daten
Spalten mit personenbezogenen Daten — Namen, Kontakt- und Bankdaten von Mietern, Eigentümern, Mitarbeitern und Kreditoren, Namen von Bearbeitern und Zuständigen sowie Freitextfelder wie Kommentare, die all das enthalten können — gehören zu einer von zwei Klassen,personal und personal_financial. Ein Key sieht eine Klasse nur mit dem passenden Grant; personal schließt personal_financial nicht ein. Ohne Grant liefert /v1/{category}/{table} die Zeilen ohne diese Spalten. ID-Spalten und property_id bleiben immer erhalten. Ausnahme: Die Buchungstexte booking_headers.booking_text und booking_positions.booking_position_text sind nicht klassifiziert und für jeden Key sichtbar, obwohl sie vereinzelt Namen enthalten.
Grants gelten für jeden Key, raw oder transformed, und haben Vorrang vor einem Spaltenfilter, der die Spalte nennt. Raw-Tabellen brauchen beide Grants (siehe oben). Ein Administrator setzt Grants im Portal; eine Änderung wirkt nach etwa einer Minute.
Property-Einschränkungen
Eintransformed-Key kann zusätzlich auf eine Liste von Property-IDs eingeschränkt sein. Category-Endpunkte liefern dann nur Zeilen dieser Properties, und eine Tabelle ohne property_id-Spalte (zum Beispiel /v1/stakeholder/creditors) liefert für einen solchen Key 403. /v1/catalog und /v1/changes werden nicht nach Property gefiltert; sie listen Tabellen, keine Zeilen. Ein Administrator setzt die Property-Liste im Portal; ein Key ohne Liste sieht alle Properties.
Konten-Einschränkungen
Ein Key kann zusätzlich auf Positionen der Reporting-StrukturTrassets-Standard eingeschränkt sein (siehe account_hierarchies unter Accounting). /v1/accounting/accounts, booking_positions, budgets und account_hierarchies liefern dann nur Zeilen, deren Konto (property_id + account_id) einer dieser Positionen zugeordnet ist. /v1/accounting/booking_headers und /v1/raw/{table_name} liefern für einen solchen Key 403, /v1/raw/tables eine leere Liste. Andere Kategorien werden nicht nach Konto gefiltert; ein Key, der ohne Kategorieauswahl erstellt wurde, ist auf Accounting beschränkt. Ein Administrator wählt die Positionen im Portal beim Erstellen des Keys; nachträglich lassen sie sich nicht ändern, dafür einen neuen Key erstellen. Ein Key ohne Positionen sieht alle Konten.
Speicherung und Sicherheit des Keys
Trassets speichert deinen API-Key niemals im Klartext. Auf unseren Servern wird nur ein HMAC-SHA-256-Hash zur Verifikation aufbewahrt. Das bedeutet: Wir können einen Key nach der Erstellung nicht wiederherstellen oder erneut anzeigen. Behandle deinen Key wie ein Passwort:- Committe ihn nicht in die Versionskontrolle.
- Rotiere Keys regelmäßig: Erzeuge im Portal einen neuen Key, stelle deine Integration um und lösche dann den alten. Die Spalte Last Used im Portal zeigt, wann ein Key zuletzt erfolgreich benutzt wurde (höchstens stündlich aktualisiert). Prüfe damit vor dem Löschen, dass der alte Key nicht mehr im Einsatz ist. Eine Ein-Klick-Rotation gibt es nicht.
- Beschränke jeden Key auf die minimal nötige Zugriffsstufe für deine Integration.
Authentifizierungsfehler
Wenn der Key fehlt, ungültig ist oder nicht die erforderliche Zugriffsstufe hat, liefert die API eine RFC-7807-Problem-Antwort.401 Unauthorized
X-API-Key-Header enthielt.
403 Forbidden
Invalid API key) oder deaktiviert (API key is disabled), oder er ist gültig, aber der angeforderte Endpunkt oder die Datenstufe ist nicht in deinem Abonnement enthalten. Das Feld detail zeigt, welcher Fall vorliegt. Kontaktiere deinen Account-Administrator oder den Trassets-Support, um deinen Zugang zu ändern.