Authentifizierung
Wie Sie sich mit einem API-Schlüssel authentifizieren, welche Scopes es gibt und wie Sie Schlüssel sicher verwalten.
Der Authorization-Header
Senden Sie Ihren Schlüssel bei jeder Anfrage als Bearer-Token mit:
GET /api/v1/me HTTP/1.1
Host: app.klantly.com
Authorization: Bearer kly_4fZ2mQ8v...Ohne gültigen Schlüssel folgt 401 mit dem Code unauthenticated oder invalid_api_key.
Wie ein Schlüssel aussieht
Ein Schlüssel beginnt immer mit kly_, gefolgt von 49 Zeichen. Am Präfix ist ein offengelegter Schlüssel erkennbar, zum Beispiel für Secret Scanning auf GitHub. Die letzten Zeichen bilden eine Prüfsumme: Ein Schlüssel mit Tippfehler wird sofort abgelehnt.
Klantly speichert nur einen unumkehrbaren Fingerabdruck des Schlüssels. Niemand kann ihn später noch anzeigen, auch Klantly nicht. Haben Sie ihn verloren? Erstellen Sie einen neuen.
Scopes
Ein Schlüssel kann nur, was seine Scopes erlauben. Wählen Sie beim Erstellen Nur lesen, Vollzugriff oder eine eigene Auswahl.
| Scope | Beschreibung |
|---|---|
customers.read | Kunden und Leads lesen |
customers.write | Kunden und Leads erstellen und bearbeiten |
deals.read | Deals und Pipeline-Phasen lesen |
deals.write | Deals erstellen, bearbeiten, verschieben und archivieren |
appointments.read | Termine (mit Name, E-Mail und Telefon des Kunden), Terminarten und Verfügbarkeit lesen |
appointments.write | Termine erstellen, bearbeiten, bestätigen, absagen und abschließen (Automationen des Unternehmens laufen mit) |
appointments.delete | Termine löschen |
appointments.send | Terminnachrichten per E-Mail an Kunden senden |
tasks.read | Aufgaben, Boards und Kommentare lesen |
tasks.write | Aufgaben erstellen, bearbeiten, verschieben und abschließen sowie Kommentare schreiben |
tasks.delete | Aufgaben löschen |
work_orders.read | Arbeitsaufträge lesen, mit Name, Adresse und Kontaktdaten des Kunden |
work_orders.write | Arbeitsaufträge erstellen und bearbeiten sowie den Status ändern (Abschließen kann eine Bewertungsanfrage senden) |
work_orders.delete | Arbeitsaufträge löschen |
services.read | Servicemeldungen lesen, mit Name, Adresse und Kontaktdaten des Kunden |
services.write | Servicemeldungen erstellen und ändern, den Status anpassen und Fotos hinzufügen |
services.delete | Servicemeldungen löschen |
quotes.read | Angebote lesen, mit Positionen, Beträgen und den Kundendaten darauf |
quotes.write | Angebote erstellen und bearbeiten (nur Entwürfe) sowie im Namen des Kunden annehmen oder ablehnen |
quotes.delete | Angebote löschen |
quotes.send | Angebote per E-Mail an Kunden senden |
invoices.read | Rechnungen lesen, mit Positionen, Beträgen, Zahlungen und den Kundendaten darauf |
invoices.write | Rechnungen erstellen (auch aus einem Angebot) und bearbeiten (nur Entwürfe), stornieren, Zahlungen erfassen, gutschreiben und eine Rückerstattung erfassen |
invoices.delete | Rechnungsentwürfe löschen |
invoices.send | Rechnungen per E-Mail an Kunden senden und den Zahlungslink für den Kunden abrufen |
orders.read | Webshop-Bestellungen lesen, mit Positionen, Adressen und den Kontaktdaten des Kunden |
orders.write | Den Status von Webshop-Bestellungen ändern (der Kunde erhält dann eine E-Mail), Sendungsverfolgung eintragen und Notizen schreiben |
messages.read | Unterhaltungen und Nachrichten im Posteingang lesen |
messages.send | Nachrichten an Kunden senden und Unterhaltungen schließen |
reviews.read | Bewertungen und Bewertungsanfragen lesen |
reviews.write | Bewertungsanfragen an Kunden senden (eine Bewertung selbst anlegen ist nicht möglich) |
meta_copilot.read | Stand und Meldungen des Meta-Copiloten lesen |
meta_copilot.write | Den Meta-Copiloten per Notstopp anhalten, Chancen umsetzen lassen oder ablehnen und Vorschläge genehmigen oder ablehnen (das Mandat lässt sich nur in der App einstellen) |
users.read | Benutzer des Unternehmens lesen |
company.read | Unternehmensdaten lesen |
webhooks.manage | Webhook-Endpunkte verwalten |
events.read | Events abrufen |
Ein Schlüssel erhält nie mehr Rechte als der Administrator, der ihn erstellt, bearbeitet oder erneuert: Berechtigungen, die Sie selbst nicht haben, können Sie nicht vergeben. Fehlt ein Scope, folgt 403 mit dem Code insufficient_scope, und required_scope nennt den benötigten Scope.
Ein Scope allein reicht manchmal nicht: Gehört der Endpunkt zu einer Funktion, die nicht im Paket Ihres Unternehmens enthalten ist — zum Beispiel das Pipeline-Board, Angebote, Rechnungen, Arbeitsaufträge, der Webshop oder Bewertungen —, folgt 403 mit dem Code feature_not_available, und das Feld feature nennt die fehlende Funktion. Scopes, die Ihr Unternehmen nicht nutzen kann, können Sie auch keinem Schlüssel geben.
Ablaufdatum, IP-Allowlist und Erneuern
- Ablaufdatum: 30, 90 oder 365 Tage oder unbegrenzt. Standard sind 365 Tage. In Klantly sehen Sie, welche Schlüssel bald ablaufen.
- IP-Allowlist: Beschränken Sie einen Schlüssel auf die IP-Adressen oder Bereiche (CIDR) Ihres Servers.
- Erneuern: Sie erhalten einen neuen Schlüssel mit denselben Einstellungen. Der alte bleibt auf Wunsch noch 1 Stunde, 24 Stunden oder 7 Tage gültig, damit Ihre Anbindung ohne Unterbrechung umstellen kann. Wurde der Schlüssel offengelegt, wählen Sie keine Überschneidung: Der alte funktioniert dann sofort nicht mehr.
Wenn ein Schlüssel offengelegt wurde
- Widerrufen Sie den Schlüssel sofort unter Integrationen → API. Er funktioniert ab sofort nicht mehr.
- Erstellen Sie einen neuen Schlüssel und hinterlegen Sie ihn in Ihrer Anbindung.
- Prüfen Sie im Tab Nutzung, welche Anfragen mit dem alten Schlüssel gestellt wurden.
Sichere Aufbewahrung
- Bewahren Sie Schlüssel in einer Umgebungsvariable oder einem Secrets Manager auf, nie im Quellcode.
- Verwenden Sie einen Schlüssel nur auf einem Server. Die API nimmt keine Anfragen aus einem Browser an (kein CORS).
- Geben Sie jeder Anbindung einen eigenen Schlüssel mit nur den Scopes, die sie braucht.
Zuletzt aktualisiert am 18. September 2026