In diesem Artikel erfahren Sie, wie Sie Zugriffsdaten für die öffentlichen APIs von Personio generieren und verwalten. APIs ermöglichen es Personio, Daten mit anderen Diensten oder Tools zu teilen. API-Zugriffsdaten fungieren wie ein Schlüssel, der den Informationsfluss steuert und entscheidet, was geteilt wird.
Bevor Sie beginnen
- Um den Marketplace zu nutzen und Integrationen einzurichten, benötigen Sie Bearbeitungsrechte für die Marketplace-Integration und die API.
- Um Ihre eigene individuelle Integration mithilfe unserer öffentlichen API zu erstellen, benötigen Sie den Personio Plan Core Pro.
- Personio erstellt automatisch API-Zugriffsdaten für alle Integrationen, außer für individuelle.
Mehr über API-Zugriffsdaten erfahren
API-Zugriffsdaten bauen Verbindungen auf und schützen die Kommunikation zwischen Anwendungen. In Personio erstellt das System API-Zugriffsdaten für Folgendes:
- Recruiting-API
- Integrationen von Personio
- Integrationen von Personio-Partnern
Sie können diese Zugriffsdaten nicht selbst verwalten. Sie können diese Integrationen über den Personio Marketplace aktualisieren. Das System legt die meisten API-Berechtigungen auf der Ebene fest, die für eine funktionelle Integration erforderlich ist. In der Regel erstellen und verwalten Sie die API-Zugriffsdaten für individuelle Integrationen manuell.
So funktioniert der API-Zugriff für individuelle Integrationen
Wenn Sie eine individuelle Integration einrichten, definieren Sie die entsprechenden Zugriffsrechte (z. B. ob sie Daten in Bereichen wie Mitarbeitende, Anwesenheiten, Abwesenheit und Dokumente lesen oder schreiben kann). Die Integration verwendet dann ihre API-Zugriffsdaten (Client-ID und API-Secret), um API-Anfragen zu authentifizieren.
Der API-Zugriff funktioniert anders als der rollenbasierte Zugriff für Mitarbeitende in Personio. Berechtigungen für Mitarbeitendenrollen steuern, was Benutzende in der Personio-Schnittstelle sehen und tun können, aber sie kontrollieren nicht, welche individuellen Integrationen über die API abgerufen werden können. Das bedeutet, dass Sie den API-Zugriff nicht anhand von Berechtigungen für Mitarbeitendenrollen nur auf die Mitarbeitenden beschränken können, die eine bestimmte Rolle haben.
Hinweis:
Alle Personen mit Zugriff auf API-Zugriffsdaten können fast alle Daten aus dem Personio Account über die API abrufen, unabhängig von ihren Berechtigungen in Personio. Die Berechtigungen der Mitarbeitendenrolle gelten nur für die Schnittstelle. Sie beschränken nicht, was über die API abgerufen werden kann. Gewähren Sie nur vertrauenswürdigen Personen Zugriff auf API-Zugriffsdaten.
API-Zugriffsdaten für individuelle Integrationen generieren
So generieren Zugriffsdaten für individuelle Integrationen:
- Navigieren Sie zu Marketplace > Verbundene Integrationen.
- Klicken Sie oben rechts auf dem Bildschirm auf Individuelle Integration erstellen. Dieser Button ist nur verfügbar, wenn Sie über den Personio Plan Core Pro verfügen. Wenn Sie ihn nicht sehen können, überprüfen Sie Ihren aktuellen Plan unter Einstellungen > Account & Support > Abonnement & Abrechnung, um sich zu vergewissern, dass Sie auf Core Pro sind.
- Konfigurieren Sie die Einrichtung.
Hinweis:
Schreibberechtigungen schließen keinen Lesezugriff ein. Wenn Sie Daten über unsere APIs abrufen möchten, müssen Sie auch Leseberechtigungen gewähren.
Die folgende Tabelle zeigt, was ein Drittanbietersystem mit den jeweiligen Berechtigungen tun kann. Einige Berechtigungen sind nur für den Lesezugriff verfügbar. Details zu den Endpunkten finden Sie im Developer Hub.
Integrationsberechtigungen |
Leseberechtigungen | Schreibberechtigungen |
|---|---|---|
Mitarbeitende |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Gestatten Sie Drittanbietern, in Personio Daten zu erstellen und zu aktualisieren. |
Anwesenheiten |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Gestatten Sie Drittanbietern, in Personio Daten zu erstellen, zu aktualisieren und zu löschen. |
Abwesenheit |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Gestatten Sie Drittanbietern, in Personio Daten zu erstellen und zu aktualisieren. |
Dokumente |
Gestatten Sie Drittanbietern, Dokumentkategorie-ID's aus Personio abzurufen. | Gestatten Sie es Drittanbietern, Dokumente in Personio zu erstellen. |
Individuelle Berichte |
Gestatten Sie Drittanbietern, alle vorhandenen individuellen Berichte aus Personio abzurufen. Aktivieren Sie diese Checkbox, um alle Attribute in einem individuellen Bericht abrufbar zu machen. Dies gilt auch, wenn sie nicht unter Lesbare Mitarbeitenattribute erscheinen. |
Nicht zutreffend. |
| Vergütungen | Gestatten Sie Drittanbietern, Vergütungsdaten aus Personio abzurufen. | Gestatten Sie Drittanbietern, Vergütungsdaten in Personio zu erstellen und zu aktualisieren. |
Recruiting |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Gestatten Sie Drittanbietern, in Personio Daten zu erstellen und zu aktualisieren. |
Webhooks |
Rufen Sie Metadaten zum Webhook ab. |
Webhooks erstellen, aktualisieren und löschen. Lese- und Schreibberechtigungen haben keinen Einfluss darauf, ob ein Webhook getriggert wird. Ein Webhook funktioniert auch nach dem Erstellen weiter, unabhängig von der Berechtigungseinstellungen. Erfahren Sie in unserer technischen Dokumentation mehr über Webhooks. |
Organisationseinheiten |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Nicht zutreffend. |
Gesellschaften |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Nicht zutreffend. |
Kostenstellen |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Nicht zutreffend. |
Standorte |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Nicht zutreffend. |
Berichte |
Gestatten Sie Drittanbietern, Daten aus Personio abzurufen. | Nicht zutreffend. |
Hinweis:
Die Aktivierung des Zugriffs auf Anwesenheiten ermöglicht es Ihrer Integration auch, den Projekt-API-Endpunkt (/v2/projects) für individuelle Integrationen zu nutzen. Es gibt keine separate Projekt-Berechtigung in den Zugriffsdateneinstellungen.
Die Attributnamen in den Selektoren Lesbare Mitarbeitendenattribute und Lesbare Gesellschaften werden auf Englisch angezeigt, unabhängig von der Sprache Ihres Personio Accounts. Wenn Sie ein Attribut nicht finden können, suchen Sie nach seinem englischen Äquivalent.
Ihre API-Anfragen authentifizieren
Nach der Generierung der API-Zugriffsdaten müssen Sie diese gegen ein Bearer-Token eintauschen, bevor Sie einen API-Aufruf tätigen. Sie können Ihren Clientschlüssel nicht direkt als Bearer-Token verwenden.
So erhalten Sie ein Bearer-Token:
- Senden Sie eine POST-Anfrage an den Auth-Endpunkt: POST https://api.personio.de/v2/auth/token mit Inhaltstyp: application/x-www-form-urlencoded and the following parameters: grant_type=client_credentials, client_id={your_client_id}, client_secret={your_client_secret}
- Die Antwort gibt ein Bearer-Token zurück. Fügen Sie es in den Autorisierungs-Header jeder nachfolgenden API-Anfrage ein: Autorisierung: Bearer {token}
Bearer-Tokens sind 24 Stunden lang gültig. Generieren Sie nach Ablauf ein neues Token. Sie finden Ihre Client-ID und Ihren Clientschlüssel unter Einstellungen > Sicherheit & Integrationen > API-Zugriffsdaten.
API-Zugriffsdaten für individuelle Integrationen aktualisieren
So aktualisieren Sie die Berechtigungen für individuelle Integrationen:
- Gehen Sie zu Marketplace > Verbundene Integrationen.
- Klicken Sie auf die Integration, die Sie aktualisieren möchten.
- Nehmen Sie Ihre Änderungen im Fenster vor, das nun erscheint.
- Speichern Sie Ihre Einstellungen.
Sie können von hier aus auch die API-Zugriffsdaten zurücksetzen, indem Sie der Anleitung folgen.
API-Zugriffsdaten für individuelle Integrationen trennen oder deaktivieren
So trennen oder deaktivieren Sie API-Zugriffsdaten für individuelle Integrationen:
- Gehen Sie zu Marketplace > Verbundene Integrationen.
- Klicken Sie in der Spalte Aktion auf die drei Punkte.
- Klicken Sie auf Deaktivieren, um Zugriffsdaten vorübergehend zu deaktivieren.
- Klicken Sie auf Trennen, um die Zugriffsdaten dauerhaft zu löschen.
Wenn Sie sich nicht sicher sind, ob eine Integration noch verwendet wird, wählen Sie Deaktivieren anstatt Trennen. Das Deaktivieren macht die Integration inaktiv, behält sie aber in Marketplace > Verbundene Integrationen bei. Wenn die Integration aktiv ist, können Sie sie wieder aktivieren. Eine Trennung entfernt die Zugriffsdaten dauerhaft und kann nicht rückgängig gemacht werden.
Auf die technische Dokumentation zugreifen
Die gesamte API-Dokumentation finden Sie in unserem Developer Hub. Dazu gehören Endpunkte, Webhooks, Datendetails und Tutorials. Der Developer Hub ist in zwei Versionen mit unterschiedlichem Inhalt verfügbar. Die Webhook-Informationen sind in Version 2.0 enthalten. Um zwischen den beiden Versionen zu wechseln, klicken Sie auf die Versionsnummer oben auf der Startseite.