Einen API-Schlüssel anlegen

Eine API ist eine Tür an der Rückseite Ihres Kontos. Wo Sie in Ihrer Verwaltung klicken, kann ein anderes Programm durch diese Tür Ihre Daten direkt abrufen: Ihre Produkte, Ihre Preise, Ihre freien Plätze, Ihren Verkauf.

Das ist nützlich, wenn Sie zum Beispiel:

• auf Ihrer eigenen Website zeigen möchten, welche Führungen diese Woche noch Platz haben;
• Ihre Buchhaltung Ihre Umsatzzahlen automatisch abholen lassen wollen;
• Ihre Mitgliederliste mit einem anderen Programm verbinden möchten.

Wer diese Anbindung baut — Ihre Webagentur, Ihr Buchhaltungspaket, ein Bekannter, der programmieren kann — braucht zwei Dinge von Ihnen: die Adresse und einen Schlüssel. Beides finden Sie auf einem einzigen Bildschirm.

Gut zu wissen: Die API gehört zu einem größeren Tarif. Auf einem kleineren Tarif steht API-Zugang nicht in Ihrem Menü; landen Sie trotzdem auf dem Bildschirm, sehen Sie eine Erklärung und eine Schaltfläche Zum Abonnement, aber keine Schlüssel.

Wo Sie hinmüssen

Öffnen Sie im linken Menü Einstellungen → API-Zugang. Nur die Rolle Eigentümer sieht diesen Bildschirm.

Oben stehen zwei Reiter: Schlüssel und Webhooks. Dieser Artikel behandelt den ersten; die Webhooks stehen in Webhooks einrichten.

Auf dem Reiter Schlüssel sehen Sie drei Blöcke:

1. Die Anbindung — die Adresse und die technische Beschreibung. Diese beiden Angaben geben Sie an denjenigen weiter, der die Anbindung baut.
2. Neuer Schlüssel — hier legen Sie einen an.
3. Schlüssel — was bereits besteht und wann es zuletzt genutzt wurde.

Einen Schlüssel anlegen

Schritt 1. Vergeben Sie einen Namen. Nicht Ihren eigenen Namen, sondern den Namen dessen, was am anderen Ende hängt: „unsere Website“, „Buchhaltung“, „Newsletter“. Dieser Name ist nur für Sie. Er steht später in der Liste, neben „zuletzt genutzt“. So wissen Sie in einem Jahr noch, welcher Schlüssel wozu gehört — und welchen Sie bedenkenlos widerrufen können.

Schritt 2. Haken Sie an, was der Schlüssel darf. Unter Was darf dieser Schlüssel? stehen die Rechte, im Fachjargon Scopes. Lesen ist bereits angehakt:

Recht	Was das Programm darf
Lesen	Ihren Katalog, Ihre Preise, freie Plätze, Rabatte, Gutscheine und Jahreskarten ansehen — und auch Ihre Bestellungen, Tickets, Scans und Käufer, mit Name und E-Mail-Adresse.
Schreiben	Bestellungen anlegen, bezahlen lassen, stornieren und erstatten, eine Rechnung anfordern, Tickets entwerten und erneut senden, Besucher einchecken sowie Gutscheine und Jahreskarten ausstellen, einlösen oder verlängern.
Webhooks	Einstellen, dass wir eine Benachrichtigung an eine eigene Adresse senden, sobald etwas passiert.
Extern bezahlt	Eine Bestellung ohne Zahlungsanbieter als bezahlt markieren (Überweisung, bar). Funktioniert nur zusammen mit Schreiben.

Haken Sie nur an, was wirklich nötig ist. Eine Website, die lediglich zeigen soll, welche Plätze frei sind, kommt mit Lesen aus. Bekommt dieser Schlüssel auch Schreiben, dann kann ein Fehler in dieser Website Bestellungen anlegen oder erstatten, die Sie nicht wollen.

Seien Sie mit Extern bezahlt besonders sparsam: Wer das darf, kann Tickets ausgeben, ohne dass Geld hereinkommt. Geben Sie es nur einer Kasse oder Buchhaltung, die Sie selbst verwalten.

Sie müssen mindestens ein Recht anhaken. Ein Schlüssel ohne Rechte dürfte nichts, und das ist die am schwersten auffindbare Art von Fehler — deshalb weist der Bildschirm ihn ab.

Schritt 3 (optional). Setzen Sie ein Ablaufdatum. Lassen Sie das Feld Läuft ab am (optional) leer, bleibt der Schlüssel gültig, bis Sie ihn selbst widerrufen. Tragen Sie ein Datum ein, funktioniert er an diesem Tag noch und endet danach von selbst. Das Datum muss in der Zukunft liegen. Praktisch, wenn Sie jemanden vorübergehend mitschauen lassen: Sie müssen später nicht mehr daran denken.

Schritt 4 (optional). Testschlüssel. Haken Sie Testschlüssel (Sandbox) für denjenigen an, der noch baut. Ein solcher Schlüssel liest dieselben Daten wie ein normaler. Hat er auch Schreiben, legt er nur Testbestellungen an: Sie gehen nie an Ihren Zahlungsanbieter, zählen nicht zu Ihrem Umsatz und werden nach 24 Stunden automatisch entfernt. Ein Tippfehler kann dann keine echte Zahlung und keine echte Erstattung auslösen. Webhooks einrichten kann ein Testschlüssel nicht.

Achtung: Bis sie entfernt ist, hält eine Testbestellung durchaus einen echten Platz fest, und die Bestätigungsmail geht wirklich hinaus. Lassen Sie mit einem Produkt oder Zeitslot testen, den Sie eigens dafür anlegen.

Sie erkennen einen Testschlüssel am Anfang: Er beginnt mit pv_test_ statt pv_live_.

Schritt 5. Klicken Sie auf „Schlüssel erstellen“.

Den Schlüssel sehen Sie nur einmal

Direkt nach dem Anlegen erscheint der Schlüssel in einem Rahmen. Das ist das einzige Mal, dass Sie ihn sehen.

Kopieren Sie ihn jetzt und geben Sie ihn sofort weiter. Laden Sie die Seite neu, ist er weg.

Das ist keine Unbequemlichkeit, sondern Schutz. Wir bewahren Ihren Schlüssel nicht auf: Wir behalten nur eine Art Fingerabdruck davon, mit dem wir ihn wiedererkennen, aber nicht zurücklesen können. Käme jemand jemals an unsere Datenbank, hätte er damit trotzdem keinen Zugang zu Ihren Daten. Die Kehrseite ist, dass auch wir ihn Ihnen nicht mehr zeigen können.

Verloren? Kein Problem: Legen Sie einen neuen an und widerrufen Sie den alten.

Behandeln Sie einen Schlüssel wie einen Schlüssel

Wer den Schlüssel hat, darf das, was darauf angehakt ist — ohne Passwort und ohne Ihr Konto zu öffnen. Also:

• schicken Sie ihn nicht in einen gewöhnlichen Gruppenchat, wo er stehen bleibt;
• schreiben Sie ihn nicht in den sichtbaren Code Ihrer Website;
• geben Sie jeder Anbindung einen eigenen Schlüssel. Dann können Sie einen widerrufen, ohne den Rest zu zerstören, und Sie sehen in der Liste, welcher noch genutzt wird.

Einen Schlüssel widerrufen

Klicken Sie in der Liste neben dem Schlüssel auf Widerrufen und bestätigen Sie.

Ab diesem Moment funktioniert er nicht mehr. Die Zeile bleibt in der Liste stehen, mit dem Vermerk „Widerrufen“: So können Sie später noch nachsehen, welche Anbindung wann bestand.

Widerrufen Sie einen Schlüssel, wenn:

• Sie das Werkzeug, das ihn nutzte, nicht mehr einsetzen;
• Sie ihn verloren haben oder er irgendwo herumliegt;
• jemand geht, der ihn hatte.

Das Anlegen und Widerrufen eines Schlüssels erscheint auch im Aktivitätsprotokoll dessen, der es getan hat (Einstellungen → Mitarbeiter, diese Person, Reiter Aktivität), mit dem Zeitpunkt. Der Schlüssel selbst steht dort nie.

Wann wurde er zuletzt genutzt?

Unter jedem Schlüssel steht, wann damit zuletzt etwas abgerufen wurde. Steht dort seit Monaten „noch nicht genutzt“, hängt vermutlich nichts mehr daran. Widerrufen Sie ihn ruhig — eine Tür, die niemand benutzt, muss nicht offen bleiben.

Was Sie an den Erbauer der Anbindung weitergeben

Drei Dinge:

1. die API-Adresse aus dem Block Die Anbindung;
2. die technische Beschreibung (der Link, der auf openapi.json endet) — damit sieht eine Entwicklerin sofort alles, was möglich ist;
3. den Schlüssel selbst und die Rechte, die Sie angehakt haben.

Mehr braucht er nicht.

Und dann?

Sie haben die Adresse und den Schlüssel. Was danach kommt, ist Arbeit für den, der die Anbindung baut — und dem schicken Sie das Entwicklerportal. Dort steht die vollständige Referenz, mit Codebeispielen in vier Sprachen und einer Datei, die sich direkt in Postman oder Insomnia importieren lässt.

• Was ist eine API, und brauche ich das? — falls Sie erst wissen möchten, worum es überhaupt geht.
• Webhooks — Ihrer Website mitteilen, dass etwas verkauft wurde, ohne dass sie ständig nachfragen muss.
• Webhooks einrichten — der Reiter Webhooks auf demselben Bildschirm, Schritt für Schritt.