Manuelle Aufgaben in der Awardco-Plattform, wie das Hochladen von Benutzerdateien oder das Erstellen von Berichten, können mühsam und zeitaufwendig sein. Durch die Verwendung von API-Schlüsseln können Sie diese Prozesse automatisieren und so Zeit und Aufwand sparen. Dieser Artikel erklärt, was API-Schlüssel sind, welche Möglichkeiten sie bieten und wie Sie sie innerhalb Ihrer Organisation über das API-Schlüssel-Verwaltungstool verwenden können.
Hinweis: Die Berechtigungen, die Sie für Ihren API-Schlüssel auswählen, hängen davon ab, welche Awardco-Produkte Sie verwenden:
- Awardco Recognition: Sie benötigen möglicherweise eine breite Palette von Berechtigungen, einschließlich sozialer Feeds, Anerkennungspostings und Berichterstellung.
- Awardco Engage: Da sich Engage auf Mitarbeiterbefragungen konzentriert, sind Ihre API-Anforderungen wahrscheinlich auf die Benutzerverwaltung beschränkt, um Ihre Umfrage-Zielgruppen aktuell zu halten.
- Was ist API?
- Aktivieren der API-Schlüssel-Berechtigung
- Zugriff auf das API-Schlüssel-Verwaltungstool
- Erstellen eines neuen API-Schlüssels
- Verwalten von API-Schlüsseln
- Übergang von klassischen API-Schlüsseln
- Erforderliche Berechtigungen für Integrationen
Was ist API?
API (Application Programming Interface) ist eine Möglichkeit, wie zwei Programme miteinander kommunizieren können. Es stellt eine Reihe von Befehlen und Anfragen bereit, die ein Programm (wie Awardco) von externen Quellen akzeptieren kann. Die meisten mobilen Apps verwenden APIs, um mit ihren übergeordneten Systemen zu kommunizieren.
Die API von Awardco verwendet HTTP, dasselbe Protokoll, das von Websites genutzt wird, was die Kommunikation vereinfacht und es ermöglicht, API-Aufrufe direkt aus einem Browser heraus zu tätigen.
Die API von Awardco unterstützt zwei Hauptanfragetypen:
- GET: Fordert Informationen aus der Datenbank an, z. B. das Abrufen von Berichten im .csv- oder .json-Format.
- POST: Aktualisiert Informationen in der Datenbank. Zum Beispiel können Sie Benutzer aktualisieren, Anerkennungen posten oder Belohnungen verwalten.
Was ist mit API möglich?
Häufige Anwendungsfälle sind:
- Benutzerverwaltung: Synchronisieren von Mitarbeiterdaten (wichtig für Engage und Recognition).
- Automatisierung: Automatisieren von Auszeichnungen und Anerkennungen (nur Recognition).
- Soziale Feeds: Abrufen von Feed-Informationen für externe Anzeigen (nur Recognition).
Um eine Datei über eine API zu senden, muss die Datei zugänglich und korrekt codiert sein. Es gibt drei Hauptmethoden, dies zu handhaben:
- Speichern der Datei auf einem FTP- oder öffentlich zugänglichen Server.
- Verwendung eines API-Dienstes (z. B. Postman), um die Anfrage zu erstellen.
- Verwendung von Programmiersprachen wie C#, cURL oder JavaScript, um die Anfrage zu senden.
Obwohl die API einen leistungsstarken Zugriff auf die Awardco-Plattform bietet, sind die Kunden vollständig für deren Nutzung verantwortlich.
Weitere Informationen finden Sie in unserer öffentlichen API-Dokumentation.
Aktivieren der API-Schlüssel-Berechtigung
Standardmäßig können nur Super-Admin-Benutzer API-Schlüssel verwalten. Um anderen Rollen die Verwaltung und Erstellung von API-Schlüsseln zu erlauben:
- Wählen Sie auf der Startseite die Schaltfläche Admin unten im linken Navigationsmenü.
- Wählen Sie „Benutzer“ und dann „Berechtigungen“ im linken Navigationsmenü.
- Klicken Sie auf das Drei-Punkte-Symbol neben der Rolle, die Sie bearbeiten möchten, und wählen Sie Bearbeiten.
- Navigieren Sie zu den Berechtigungseinstellungen und aktivieren Sie das Kontrollkästchen neben „API-Schlüssel“.
- Klicken Sie auf Speichern & Anwenden.
Zugriff auf das API-Schlüssel-Verwaltungstool
Awardco stellt ein spezielles API-Schlüssel-Verwaltungstool bereit, mit dem Sie bestimmte API-Schlüssel für verschiedene Aktionen verwalten können, wie z. B. das Senden von Anerkennungen, das Abrufen von Feeds oder das Erstellen von Benutzern. Anstatt einen einzigen, allmächtigen API-Schlüssel zu verwenden, unterteilt Awardco die Schlüssel in separate Aktionen basierend auf Ihren Bedürfnissen.
So greifen Sie auf das API-Schlüssel-Verwaltungstool zu:
- Wählen Sie auf der Startseite die Schaltfläche Admin unten im linken Navigationsmenü.
- Wählen Sie „Plattform“, dann „Integrationen“ und anschließend „API-Einstellungen“ im linken Navigationsmenü.
Im API-Schlüssel-Verwaltungstool können Sie:
- Bestimmte API-Schlüssel für verschiedene Aufgaben anzeigen und verwalten (z. B. das Senden von Anerkennungen, das Abrufen von Berichten).
- Rollen und Berechtigungen zuweisen, wer innerhalb Ihrer Organisation API-Schlüssel verwalten darf.
- Nachverfolgen, wer jeden API-Schlüssel erstellt hat und wann er erstellt wurde.
- Sicherstellen, dass API-Schlüssel gehasht und gesalzen sind (sie werden nicht im Klartext gespeichert).
- API-Schlüssel bei Bedarf löschen.
- Beachten, dass Benutzer, die sich als andere ausgeben, keine API-Schlüssel generieren können.
- API-Schlüssel sicher an vertrauenswürdige Personen senden.
Erstellen eines neuen API-Schlüssels
So erstellen Sie einen neuen API-Schlüssel:
- Klicken Sie auf der Seite API-Schlüssel auf die Schaltfläche „+ Neuer API-Schlüssel“.
- Geben Sie einen Schlüsselnamen ein.
- Wählen Sie die Berechtigungen aus, die der Schlüssel haben soll.
- Für Recognition-Kunden: Wählen Sie Berechtigungen aus, die für Ihre Integration relevant sind (z. B. Custom Feed für ScreenCloud).
- Für Engage-Only-Kunden: In der Regel benötigen Sie nur Berechtigungen im Zusammenhang mit Benutzer-Datentransfers, um Ihre Umfrage-Zielgruppen aktuell zu halten. Wir empfehlen, nur folgende auszuwählen:
- Benutzer aktivieren, Benutzer archivieren, Benutzer erstellen, Benutzer importieren, Profilbild, Passwort zurücksetzen, Benutzer existiert und Benutzer.
- Wenn Sie einen API-Schlüssel für eine Awardco-Integration einrichten, siehe den Abschnitt Erforderliche Berechtigungen für Integrationen weiter unten.
- Legen Sie die Ablaufzeit oder das Ablaufdatum des Schlüssels fest.
- Das maximale Ablaufdatum liegt drei Jahre ab dem heutigen Datum. Es wird empfohlen, API-Schlüssel regelmäßig auszutauschen.
- Klicken Sie auf Weiter.
- Wählen Sie, ob der Schlüssel sofort generiert oder sicher an eine andere Person gesendet werden soll.
- Überprüfen Sie die Details und schließen Sie den Vorgang ab, indem Sie auf API-Schlüssel generieren oder sicher senden klicken.
Wichtig: Kopieren und speichern Sie den API-Schlüssel sofort nach der Generierung sicher. Aus Sicherheitsgründen wird er nicht erneut angezeigt. Für weitere Informationen zu bewährten Methoden und Tipps zu API-Schlüsseln lesen Sie diesen Support-Artikel.
Verwalten von API-Schlüsseln
Anzeigen und Bearbeiten von API-Schlüssel-Details
Um Details eines API-Schlüssels anzuzeigen, klicken Sie auf den Namen des API-Schlüssels, um ein Detailfenster zu öffnen, das zeigt:
- Schlüsselname.
- Die ersten sechs Ziffern des Schlüssels.
- Name des Erstellers.
- Status.
- Berechtigungen.
- Erstellungsdatum.
- Ablaufdatum.
- Zuletzt verwendetes Datum.
Um den Namen oder das Ablaufdatum eines API-Schlüssels zu bearbeiten, klicken Sie auf Bearbeiten und nehmen Sie Änderungen vor. Speichern Sie Ihre Änderungen, wenn Sie fertig sind.
Widerrufen eines API-Schlüssels
Das Widerrufen eines API-Schlüssels deaktiviert diesen dauerhaft, wodurch alle damit verbundenen Integrationen nicht mehr funktionieren. Diese Aktion kann nicht rückgängig gemacht werden.
So widerrufen Sie einen API-Schlüssel:
- Klicken Sie auf das Drei-Punkte-Symbol neben dem Schlüssel.
- Wählen Sie „Widerrufen“.
- Bestätigen Sie durch Klicken auf „API-Schlüssel widerrufen“.
Widerrufene Schlüssel werden in den Tab Archiviert verschoben.
Erneutes Senden eines API-Schlüssels
Wenn ein API-Schlüssel den Status „Nicht akzeptiert“ anzeigt oder nicht innerhalb von 24 Stunden akzeptiert wurde, können Sie ihn erneut senden.
- Klicken Sie auf das Drei-Punkte-Symbol neben dem Schlüssel.
- Wählen Sie „Erneut senden“. Der API-Schlüssel wird an die E-Mail-Adresse gesendet, die bei der Erstellung des Schlüssels angegeben wurde.
Klonen eines API-Schlüssels
So klonen Sie einen API-Schlüssel:
- Klicken Sie auf das Drei-Punkte-Symbol neben dem Schlüssel und wählen Sie „Klonen“.
- Aktualisieren Sie bei Bedarf den Namen, die Berechtigungen oder das Ablaufdatum.
- Folgen Sie dem gleichen Prozess zum Generieren oder Senden des Schlüssels wie unter „Erstellen eines neuen API-Schlüssels.“ beschrieben.
Anzeigen archivierter Schlüssel
Um widerrufene oder archivierte API-Schlüssel anzuzeigen, navigieren Sie zum Tab Archiviert in den API-Schlüssel-Einstellungen. Widerrufene Schlüssel können nicht wiederhergestellt werden, aber sie können geklont werden, um eine Kopie zu erstellen.
Übergang von klassischen API-Schlüsseln
Obwohl klassische API-Schlüssel vorerst weiterhin funktionieren, empfehlen wir die Migration zum neuen System für erhöhte Sicherheit und bessere Kontrolle über Ihre Integrationen.
Finden Ihres klassischen API-Schlüssels
Ihr klassischer API-Schlüssel wurde auf die neue API-Schlüssel-Verwaltungsseite verschoben. Sie finden ihn nun am unteren Rand der API-Einstellungsseite.
Wie man von klassischen API-Schlüsseln migriert
Um sicher von Ihrem klassischen API-Schlüssel zu wechseln:
- Erstellen Sie neue berechtigte Schlüssel: Generieren Sie separate API-Schlüssel für jede Integration mit den Schritten unter „Erstellen eines neuen API-Schlüssels“ oben. Stellen Sie sicher, dass jeder Schlüssel nur die spezifischen Berechtigungen für seine Integration hat.
- Aktualisieren Sie Ihre Integrationen: Ersetzen Sie den klassischen API-Schlüssel in jeder Integration durch den entsprechenden neuen berechtigten Schlüssel.
- Löschen Sie Ihren klassischen API-Schlüssel: Sobald alle Integrationen aktualisiert sind, klicken Sie auf die Schaltfläche „Klassischen API-Schlüssel löschen“ am unteren Rand der API-Einstellungsseite.
Erforderliche Berechtigungen für Integrationen
Eine Liste der Integrationen, die API-Schlüssel verwenden, und die jeweils erforderliche Berechtigung:
- ScreenCloud - Custom Feed
- Qualtrics - Externe Anerkennung
- Speakap - Sozialer Feed
- Sworkit - Massenbelohnung
- Paycom - Benutzer importieren
- Awardco Connect (für alle Kunden) - Ein Awardco-Vertreter wird Sie bezüglich der spezifischen Berechtigungen beraten, die Ihr API-Schlüssel benötigt. In den meisten Fällen sind nur wenige Berechtigungen erforderlich.
If you have any questions, please contact Awardco Admin Support.