Zum Inhalt springen
craftdexDocs

API-Schlüssel

Wer API-Schlüssel erstellt, auf welche Daten und IP-Adressen man sie beschränkt, wie lange sie gelten und wie man sie widerruft.

Erstellen

Firmenprofil → Plattform → API-Schlüssel → API-Schlüssel erstellen

  • Erstellen kann nur der Inhaber des Betriebs. Er bestätigt mit seinem Passwort.
  • Pflicht ist ein Name, zum Beispiel „Wechsel zu Firma XY“. Er erscheint in der Liste, in den Benachrichtigungen und im Protokoll.
  • Laufzeit: 7, 30 oder 90 Tage. Danach ist der Schlüssel ungültig, verlängern lässt er sich nicht.
  • Zugriff: alle Daten oder nur ausgewählte Bereiche, siehe unten.
  • IP-Adressen: uneingeschränkt oder nur von festgelegten Adressen, siehe unten.
  • Je Betrieb gelten höchstens 3 Schlüssel gleichzeitig.
  • Der Schlüssel wird nur einmal angezeigt. CraftDex speichert ihn nicht, nur einen Hashwert und den Anfang zum Wiedererkennen (cdx_Ab12…).

Ein Schlüssel sieht so aus: cdx_ und 43 Zeichen aus Buchstaben und Ziffern.

Zugriff und IP-Adressen werden beim Erstellen festgelegt und lassen sich danach nicht ändern. Für andere Einstellungen erstellen Sie einen neuen Schlüssel und widerrufen den alten.

Zugriff: alle Daten oder einzelne Bereiche

EinstellungWas der Schlüssel liefert
Alle Datenden Komplett-Export mit allen Tabellen und Dateien, zum Beispiel für einen Anbieterwechsel oder eine eigene Sicherung
Nur ausgewählte Bereichenur die Tabellen und Dateien der gewählten Bereiche

Die Bereiche sind dieselben wie bei den Rechten der Rolle „Büro“:

BereichTabellen (Auswahl)Ablagen
Baustellensites, Aufgaben, Bautagebuch, Mängel, Pläne, Protokollesite-photos, site-defects, site-documents, site-plans, checklist-files
Plantafelassignments, plan_pending–
Mitarbeiterusers, app_roles, worker_qualificationsuser-avatars
Zeiterfassungtime_entries und weitere time_*, Arbeitszeitmodelle–
Abwesenheitenabsences–
Angebote & Rechnungenquotes, invoices, Positionen, Zahlungen, E-Mail-Versand, Einstellungeninvoice-pdfs, company-logos
Kunden & Katalogcustomers, customer_contacts, catalog_items–
Material & Lagermaterials, warehouses, stock_movements, ordersmaterial-images, warehouse-images
Werkzeuge & Maschinentools, tool_logstool-photos, tool-receipts

Bei welchem Bereich jede einzelne Tabelle steht, zeigt Tabellen und Spalten. Integrationen, Zustimmungen und Meldungen an CraftDex (company_integrations, company_agreements, support_reports, support-screenshots) gibt es nur mit allen Daten.

Beispiel Steuerberater: Bereiche Angebote & Rechnungen und Kunden & Katalog. Der Schlüssel liefert dann Angebote, Rechnungen mit PDF und XRechnung, Zahlungen und Kunden, aber keine Mitarbeiter, Arbeitszeiten oder Baustellenfotos.

Mit einem eingeschränkten Schlüssel enthalten export und export.json nur die freigegebenen Tabellen und Dateien, export.json hat zusätzlich das Feld areas. Dateien anderer Bereiche ergeben 404. Ein solcher Export zählt nicht als „letzter vollständiger Export“ des Betriebs.

IP-Adressen

EinstellungWirkung
UneingeschränktDer Schlüssel funktioniert von jeder IP-Adresse aus.
Nur vertrauenswürdige IP-AdressenAnfragen von anderen Adressen werden mit 403 ip_not_allowed abgelehnt und im Protokoll festgehalten.
  • Eine Adresse oder ein Bereich je Zeile, IPv4 oder IPv6: 203.0.113.10, 203.0.113.0/24, 2001:db8:12::/48.
  • Höchstens 20 Einträge. Bereiche müssen bei IPv4 mindestens /8, bei IPv6 mindestens /16 lang sein; 0.0.0.0/0 ist nicht erlaubt.
  • Maßgeblich ist die Adresse, von der die Anfrage bei uns ankommt. Läuft der Abruf über einen Proxy oder ein VPN, tragen Sie dessen Adresse ein. Ein mitgeschickter Kopf X-Forwarded-For wird nicht beachtet.
  • Fragen Sie den Empfänger nach seiner festen IP-Adresse. Wechselt sie (zum Beispiel bei vielen DSL-Anschlüssen täglich), ist „Uneingeschränkt“ mit kurzer Laufzeit die bessere Wahl.

Benachrichtigungen

Alle Admins des Betriebs bekommen eine E-Mail,

  • wenn ein Schlüssel erstellt wird, mit Name, Ablaufdatum, Zugriff und IP-Adressen,
  • wenn er zum ersten Mal genutzt wird, mit Zeitpunkt und IP-Adresse.

Widerrufen

Jeder Admin des Betriebs kann einen Schlüssel im Firmenprofil widerrufen. Das wirkt sofort, die nächste Anfrage mit diesem Schlüssel wird mit 401 token_revoked abgelehnt.

Protokoll

Jeder Abruf wird mit Zeitpunkt, Schlüssel, Endpunkt, Ergebnis, Datenmenge und IP-Adresse festgehalten. Die letzten 20 Zugriffe stehen im Firmenprofil unter API-Schlüssel. Das Protokoll wird nach 90 Tagen gelöscht.

Übergabe und Umgang

  • Senden Sie den Schlüssel nur im Kopf Authorization: Bearer cdx_…. Ein Schlüssel in der Adresse (?token=…) wird abgelehnt, weil Adressen in Protokollen und im Browserverlauf landen.
  • Geben Sie den Schlüssel nur an Programme und Personen, die die Daten abholen sollen, und auf einem sicheren Weg (nicht in einer offenen Gruppe oder einem Ticket).
  • Wählen Sie die kürzeste Laufzeit, die reicht, und widerrufen Sie den Schlüssel, sobald der Abruf erledigt ist.
  • Ein Schlüssel mit allen Daten öffnet alles: Mitarbeiter, Arbeitszeiten, Abwesenheiten, Kunden, Rechnungen, Fotos und Dokumente. Geben Sie nur so viel frei, wie der Empfänger braucht, und nutzen Sie feste IP-Adressen, wo es geht.

Nach Vertragsende

Schlüssel funktionieren auch nach Vertragsende weiter, bis der Betrieb gelöscht wird. Neue Schlüssel lassen sich auch im gesperrten Zugang erstellen. Mit der Löschung des Betriebs verschwinden alle Schlüssel und das Protokoll.

Auf dieser Seite