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.

Hinweis:
Wenn Sie zu Einstellungen > API-Zugriffsdaten gehen, leitet Personio Sie zu Marketplace > Verbundene Integrationen weiter. Hier finden Sie alle Ihre Integrationen, beispielsweise Marketplace-Integrationen oder individuelle Integrationen, die Sie selbst erstellt haben.

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:

1. Navigieren Sie zu Marketplace > Verbundene Integrationen.
2. 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.
3. 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. 

Voraussetzungen und Datenverfügbarkeit bei API-Berechtigungen

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.

Damit die API Vergütungen Gehaltsdaten zurückgibt, müssen Mitarbeitende einer Gesellschaft in Personio zugewiesen sein. Mitarbeitende ohne Zuweisung zu einer Gesellschaft werden nicht in den Antworten der Vergütungs-API angezeigt.

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:

1. 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}
2. 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:

1. Gehen Sie zu Marketplace > Verbundene Integrationen.
2. Klicken Sie auf die Integration, die Sie aktualisieren möchten.
3. Nehmen Sie Ihre Änderungen im Fenster vor, das nun erscheint.
4. 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:

1. Gehen Sie zu Marketplace > Verbundene Integrationen.
2. Klicken Sie in der Spalte Aktion auf die drei Punkte.
3. Klicken Sie auf Deaktivieren, um Zugriffsdaten vorübergehend zu deaktivieren.
4. 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.

API-Zugriffsdaten rotieren

Um die Zugriffsdaten für eine individuelle oder Drittanbieter-Marketplace-Integration ohne Ausfallzeit zu rotieren, erstellen Sie einen neuen Satz von Zugriffsdaten, bevor Sie die alten außer Betrieb nehmen. Mehrere aktive Zugriffsdaten können nebeneinander existieren, sodass Ihre Integration weiterhin die alten Zugriffsdaten verwenden kann, während Sie sie aktualisieren, um die neuen zu verwenden.

So setzen Sie Zugriffsdaten zurück:

1. Gehen Sie zu Marketplace > Verbundene Integrationen.
2. Wählen Sie die Integration aus.
3. Öffnen Sie den Reiter API-Zugriffsdaten, und befolgen Sie die Anweisungen zum Zurücksetzen.

Personio unterstützt keine automatisierte Rotation von Zugriffsdaten. Sie müssen die Zugriffsdaten manuell rotieren.

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.