Wie erstelle ich einen API-Schlüssel?

Worktivity stellt für Integrationen eine eigene, lesende API bereit. Ein Schlüssel gehört zur Organisation, und jede Anfrage mit diesem Schlüssel kann alles lesen, was diese Organisation enthält.

Einen Schlüssel erstellen

1. Öffnen Sie oben in der Seitenleiste den Namen des Arbeitsbereichs und wählen Sie Workspace settings.
2. Öffnen Sie den Tab API access.
3. Klicken Sie New API key, vergeben Sie einen Namen mit bis zu dreißig Zeichen und klicken Sie Create key.
4. Kopieren Sie den Schlüssel in Ihre Integration.

Die Oberfläche der App ist derzeit englisch; die Bezeichnungen oben stehen so, wie Sie sie am Bildschirm sehen.

Der Name ist nur für Sie. Nehmen Sie den Namen der Integration, die ihn benutzt, damit sich später ohne Raten entscheiden lässt, welcher Schlüssel stillgelegt wird.

Einen Schlüssel erneut ansehen

Die Liste zeigt Punkte statt des Schlüssels. Die Schaltfläche Reveal in der Zeile holt den lesbaren Wert; nach etwa fünfundvierzig Sekunden verbirgt er sich wieder. Eine Regel, dass ein Schlüssel nur einmal sichtbar wäre, gibt es hier nicht.

Wie der Schlüssel gesendet wird

Als Query-Parameter namens x_api_key und nicht als Authorization-Header:

https://open-api.useworktivity.com/Employee/List?x_api_key=YOUR_API_KEY

Pro Schlüssel gelten fünf Anfragen pro Sekunde, hundert pro Minute und hunderttausend pro Stunde. Alles darüber wird mit 429 abgewiesen.

Deaktivieren gegenüber Löschen

• Deaktivieren: der Statusschalter in der Zeile. Anfragen mit diesem Schlüssel werden ab dem nächsten Aufruf abgewiesen, ein erneutes Einschalten stellt sie wieder her. Damit lässt sich eine Integration pausieren.
• Löschen: endgültig. Alles, was auf diesem Schlüssel aufbaut, läuft ab sofort in Fehler, und der Schlüssel kommt nicht zurück.

Ein Schlüssel liest Personen, Teams, Stundenzettel, Screenshots, Projekte, Urlaubsdaten und Auswertungen der gesamten Organisation. Bewahren Sie ihn serverseitig auf, niemals im Browser, in einer mobilen App oder in einem öffentlichen Repository.

Tarif und Grenzen

Für einen neuen Schlüssel braucht es einen Tarif mit API-Zugang. Deckt Ihr Tarif ihn nicht ab, listet der Tab die vorhandenen Schlüssel trotzdem, und sie funktionieren weiter, ein offengelegter Schlüssel lässt sich also in jedem Fall deaktivieren oder löschen. Zum Höherstufen siehe den Tarif ändern.

Eine Organisation kann bis zu zehn Schlüssel halten, und der Tab zählt sie mit. Worktivity hält nicht fest, wann ein Schlüssel zuletzt benutzt wurde; deshalb gibt es dafür keine Spalte.

Dokumentation der Endpunkte

Die Schaltfläche in der Kartenkopfzeile öffnet die Entwicklerseiten auf der Worktivity-Website mit Endpunkten, Parametern und Beispielen. Den Rest der Einstellungsseite beschreibt was in den Organisationseinstellungen steht.