REST-API: Authentifizierung

Jede Anfrage an die REST-API von Personyze muss mit einem API-Schlüssel authentifiziert und über HTTPS übertragen werden. Es gibt keine öffentlichen bzw. nicht authentifizierten Endpunkte.

Wenn Sie ihn noch nicht gelesen haben, beginnen Sie mit REST-API: Überblick & Schnellstart für den grundlegenden Aufbau jeder Anfrage.

Wo Sie Ihren API-Schlüssel finden

Gehen Sie in der Personyze-Oberfläche zu Einstellungen → Integrationen → API. Jedes Personyze-Konto, auf das Sie Zugriff haben, hat einen eigenen Schlüssel — sie sind nicht austauschbar.

So senden Sie den Schlüssel

Nutzen Sie HTTP-Basic-Authentifizierung mit dem Benutzernamen api und dem Schlüssel als Passwort. Zwei übliche Wege:

Curl-Abkürzung — Zugangsdaten in der URL

Praktisch für spontane Tests und Shell-Skripte:

curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'

Authorization-Header — empfohlen für Produktionscode

Die meisten HTTP-Client-Bibliotheken lesen user:pass@host aus URLs nicht zuverlässig, und Zugangsdaten in der URL landen in Webserver-Logs und im Browserverlauf. Erstellen Sie für Produktionscode den Authorization -Header ausdrücklich:

Authorization: Basic <base64("api:" + API_KEY)>

Curl mit ausdrücklichem Header

curl https://app.personyze.com/rest/users/where/internal_id=42 \
     -H "Authorization: Basic $(printf 'api:%s' YOUR_API_KEY | base64)"

Python (requests)

import requests

r = requests.get(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    auth=('api', YOUR_API_KEY),
)
r.raise_for_status()
data = r.json()

JavaScript (fetch)

const r = await fetch(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    { headers: { Authorization: 'Basic ' + btoa('api:' + API_KEY) } }
);
const data = await r.json();

Fehlercodes der Authentifizierung

Zugriff auf mehrere Konten / Mandanten

Der API-Schlüssel legt fest, auf welchem Personyze-Konto die Anfrage arbeitet. Die Endpunkt-URL nennt das Konto nie — es ergibt sich aus dem Schlüssel. Um mit demselben Client auf mehreren Konten zu arbeiten, halten Sie einen Schlüssel pro Konto bereit und wählen vor jeder Anfrage den richtigen.

Auch Objekt-IDs gelten pro Konto: Aktion 42 in Konto A hat nichts mit Aktion 42 in Konto B zu tun. Wenn Ihr Code Personyze-IDs zusammen mit Ihren eigenen Daten speichert, sollten Sie auch die Konto-ID (oder zumindest den API-Schlüssel, mit dem sie erstellt wurden) speichern, damit Sie Anfragen später an das richtige Konto richten können.

Rate-Limits & Timeouts

• Schnelle Tracker-/SDK-Anfragen haben ein Budget von 10 Sekunden Ausführungszeit. Längere Anfragen werden zwangsweise getrennt, mit einem Fehler, der als 503 wiederholt werden kann. Die meisten REST-API-Aufrufe laufen nicht über diesen schnellen Pfad, aber komplexe Abfragen auf großen Tabellen brauchen unter Umständen eine sorgfältige Indexierung, um unter dem Limit zu bleiben.
• POST /rest/users wird pro Konto gedrosselt: höchstens ein laufender Insert gleichzeitig. Nach einer Wartezeit von 1 Sekunde in der Warteschlange werden Anfragen abgelehnt mit 400 Too many simultaneous requests. Wiederholen Sie mit exponentiellem Backoff. (Mehr dazu auf der Seite zum Objekt users.)
• Andere Endpunkte sind derzeit auf Anwendungsebene nicht begrenzt — behandeln Sie die API aber als gemeinsam genutzte Ressource und überlasten Sie sie nicht aus vielen parallelen Prozessen, wenn aufeinanderfolgende Aufrufe ausreichen.

Nächste Schritte