Authentifizierung

Jede Anfrage an die Sway-API geht über HTTPS an die Basis-URL, https://api.business.swayapp.io/v1, und trägt einen API-Schlüssel in ihrem Authorization-Header. Der Schlüssel handelt im Namen des Benutzers, der ihn erstellt hat: Er erreicht die Arbeitsbereiche, denen dieser Benutzer angehört, mit den Rechten seiner Rolle in jedem. Nur GET /health antwortet ohne Schlüssel.

Bevor Sie beginnen

• Eine Lizenz, die die Sway-API umfasst. Die Basislizenz deckt die ganze Plattform ab; eine höhere Stufe fügt die öffentliche API hinzu. Kontaktieren Sie Sway, um sie hinzuzufügen.
• Ein API-Schlüssel. Wählen Sie in der Web-App unten in der Seitenleiste Ihren Namen, dann Profil, Entwickler und API-Schlüssel erstellen: Entwickler und API-Schlüssel erklärt jedes Feld des Dialogs.

Den Schlüssel senden

Bewahren Sie den Schlüssel in einer Umgebungsvariable auf, nie in Ihrem Code, und senden Sie ihn als Bearer-Token:

export SWAY_API=https://api.business.swayapp.io/v1
curl "$SWAY_API/workspaces" \
-H "Authorization: Bearer $SWAY_API_KEY"

• Ein Schlüssel beginnt mit sway_. Die Web-App zeigt ihn nur einmal, bei seiner Erstellung: Sway speichert nur einen Digest des Schlüssels, daher kann ihn Ihnen niemand erneut zeigen.
• Der Header nimmt das Wort Bearer, mit grossem B, dann ein Leerzeichen und den Schlüssel.
• Ein fehlender, unbekannter, widerrufener oder abgelaufener Schlüssel erhält 401 unauthenticated, in jedem Fall mit derselben Meldung.

Bereiche

Ein Bereich lässt einen Schlüssel eine Ressource der API nutzen und lautet ressource:verb:

• read deckt die GET-Endpunkte der Ressource ab, etwa das Auflisten oder Durchsuchen der Rechnungen.
• write deckt jede andere Methode ab: erstellen, ändern, löschen, und Aktionen wie einen Export. Er umfasst read nicht.
• ressource:* gewährt beides. *:*, Vollzugriff in der Web-App, gewährt jede Ressource, auch jene, die die API später hinzufügt.

Ein Aufruf ohne den Bereich, den er braucht, erhält 403 permission-denied, mit dem Bereich in seiner Meldung, etwa Missing required scope: invoices:read. Der Bereich entscheidet, welche Endpunkte ein Schlüssel aufrufen darf; die Rolle seines Benutzers in jedem Arbeitsbereich entscheidet weiterhin, welche Daten er liest und was er ändern darf.

Jeder Bereich deckt die Seiten der Referenz in seiner Zeile ab:

Ablauf

Ein Schlüssel läuft 30, 60 oder 90 Tage nach seiner Erstellung ab, an einem Datum Ihrer Wahl oder nie; die Web-App beginnt mit 30 Tagen. Ein abgelaufener Schlüssel erhält 401, wie ein unbekannter: Planen Sie seinen Ersatz vor diesem Datum.

Einen Schlüssel ersetzen

Ein Schlüssel lässt sich nicht verlängern: Sie ersetzen ihn durch einen neuen, ohne Unterbruch für Ihre Software.

1. Erstellen Sie den neuen Schlüssel. Geben Sie ihm dieselben Bereiche und einen Namen, der ihn vom alten unterscheidet.
2. Stellen Sie Ihre Software um. Setzen Sie den neuen Schlüssel ein und prüfen Sie, dass seine Aufrufe gelingen.
3. Widerrufen Sie den alten Schlüssel. Wählen Sie unter Profil › Entwickler in seiner Zeile Widerrufen. Der Widerruf wirkt sofort und lässt sich nicht rückgängig machen.

Schlüssel und Arbeitsbereiche

• Ein Schlüssel erreicht jeden Arbeitsbereich seines Benutzers, mit den Rechten seiner Rolle in jedem. Kein Bereich kann ihn auf einen einzigen Arbeitsbereich begrenzen.
• Wenn das Abonnement eines Arbeitsbereichs geendet hat, antwortet jeder Aufruf auf seine Daten mit 409, Lesezugriffe eingeschlossen: siehe Fehler.

Damit Claude Ihre Arbeitsbereiche mit einem Schlüssel lesen kann, siehe Claude-Connector.