Pharen Hub API-Keys verwalten: erstellen und rotieren

API-Keys geben vertrauenswürdigen Skripten, internen Tools und Backend-Services Zugriff auf Pharen Hub, ohne dass sich ein Mensch interaktiv anmelden muss. Erstelle Keys für konkrete Automatisierungen, vergib nur die nötigen Rechte und rotiere sie, wenn sich Verantwortung oder Risiko ändern.

Behandle API-Keys wie Passwörter. Lege sie nicht im Quellcode ab, nutze sie nicht in Client-Code und schreibe sie nicht in Logs.

Key erstellen

Du erstellst API-Keys direkt in Pharen Hub.

API-Key-Einstellungen öffnen

Gehe in deinem Workspace zu Einstellungen → API-Keys.

Key benennen

Wähle einen kurzen, eindeutigen Namen wie calendar-sync-production oder docs-import-worker.

Zielbereich wählen

Wähle Ganzer Workspace für workspaceweite Automatisierungen oder Ausgewählte Teams, wenn die Integration nur in bestimmten Teams funktionieren soll.

Berechtigungen auswählen

Vergib nur die Rechte, die die Integration braucht. Listen, Docs, Kalender, Workflows und Agents können separat berechtigt werden.

Key einmal kopieren

Kopiere den generierten Key sofort. Pharen zeigt den vollständigen Key nur einmal an.

API-Key-Anfragen testen

Die Endpoint-Seiten in dieser Referenz nutzen den interaktiven Mintlify-Playground. Füge deinen Key in Try it unter Authorization ein, setze die Parameter und sende die Anfrage direkt aus der Dokumentation. Der Playground setzt baseUrl standardmässig auf https://pharen.app. Für ein lokales Backend ersetzt du diesen Wert durch http://localhost:8000.

Key verwenden

Sende den Key bei jeder Anfrage mit. Bearer-Authentifizierung wird empfohlen:

curl https://pharen.app/api/calendar/events/ \
  --request GET \
  --header "Authorization: Bearer $PHAREN_API_KEY" \
  --header "Content-Type: application/json"

Du kannst auch den Header X-API-Key verwenden, wenn ein Server-to-Server-Tool keinen Authorization-Header setzen kann:

curl https://pharen.app/api/calendar/events/ \
  --request GET \
  --header "X-API-Key: $PHAREN_API_KEY"

API-Keys von Pharen beginnen mit phk_. Speichere den vollständigen Wert in einem Secret-Manager oder in einer Umgebungsvariable wie PHAREN_API_KEY.

Berechtigungsstufen

Listen, Docs und Kalender nutzen vier Berechtigungsstufen.

Stufe	Enthaltene Scopes	Geeignet für
Keine	Keine Scopes	Keys, die keinen Zugriff auf diese Ressource haben sollen.
Lesen	`resource:read`	Reports, Sync-Jobs, Exporte und read-only Dashboards.
Schreiben	`resource:read`, `resource:create`, `resource:update`	Importe und bidirektionale Syncs, die keine Daten löschen sollen.
Vollzugriff	`resource:read`, `resource:create`, `resource:update`, `resource:delete`	Administrative Jobs, die Daten entfernen dürfen.

Workflows und Agents nutzen gezielte Ausführungsrechte.

Ressource	Lesen	Ausführen
Workflows	`workflows:read`	`workflows:read`, `workflows:run`
Agents	`agents:read`	`agents:read`, `agents:run`

Scope-Referenz

Scope	Erlaubt
`lists:read`	Gespeicherte Listendaten, Felder, Zeilen, Zellen und Ansichten lesen.
`lists:create`	Neue Listen erstellen.
`lists:update`	Listen, Felder, Zeilen, Zellen, Ansichten und Freigabedaten aktualisieren.
`lists:delete`	Listen oder Listeneinträge löschen.
`docs:read`	Dokumente, Sammlungen, Versionen, Dateien und Zugriffsmetadaten lesen.
`docs:create`	Dokumente und Sammlungen erstellen.
`docs:update`	Dokumente, Sammlungen, Dateien, Freigaben, Versionen und Aktivitätslinks aktualisieren.
`docs:delete`	Dokumente und Sammlungen löschen oder wiederherstellen.
`calendar:read`	Kalenderquellen, Ereignisse und Exporte lesen.
`calendar:create`	Kalenderquellen, Ereignisse und Importe erstellen.
`calendar:update`	Kalenderquellen und Ereignisse aktualisieren.
`calendar:delete`	Kalenderquellen und Ereignisse löschen.
`workflows:read`	Workflow-Definitionen, Versionen, Validierungsergebnisse und Ausführungspläne lesen.
`workflows:run`	Workflows ausführen. Streaming-Ausführung benötigt zusätzlich Streaming-Zugriff auf dem Key.
`agents:read`	Agents, Katalogdaten, Tools, Unterhaltungen und Logs lesen.
`agents:run`	Agent-Chat-Anfragen senden oder aktive Agent-Läufe abbrechen.

Ein Key kann nur ausführen, was seine Scopes und die Berechtigungen des erstellenden Kontos erlauben. Verliert die erstellende Person Zugriff, verlieren ihre Keys diesen Zugriff ebenfalls.

Workspace- und Team-Scope

Jeder Key gehört zu einem Workspace. Ein workspaceweiter Key kann innerhalb dieses Workspaces überall arbeiten, wo Scopes und Berechtigungen der erstellenden Person es erlauben. Team-begrenzte Keys sind strenger. Sie greifen nur bei Anfragen, die eines der ausgewählten Teams adressieren. Nutze Team-Scope für produktive Automatisierungen, die einem Team oder Bereich gehören.

Ablauf und Rotation

Ein Ablaufdatum ist optional, aber für temporäre Jobs und externe Integrationen empfohlen. Für dauerhafte produktive Jobs solltest du Keys regelmäßig rotieren.

Erstelle einen Ersatz-Key mit denselben oder engeren Scopes.
Hinterlege den neuen Key im Secret-Manager.
Prüfe, ob die Integration mit dem neuen Key funktioniert.
Widerrufe den alten Key unter Einstellungen → API-Keys.

Häufige Fehler

Status	Bedeutung	Lösung
`401 Unauthorized`	Der Key fehlt, ist fehlerhaft, abgelaufen, widerrufen oder ungültig.	Prüfe Header, Secret-Wert und Key-Status.
`403 Forbidden`	Der Key ist gültig, hat aber nicht den nötigen Scope oder Zielbereich.	Ergänze den fehlenden Scope, wähle das richtige Team oder nutze einen anderen Key.
`404 Not Found`	Die Zielressource ist für die erstellende Person nicht sichtbar.	Prüfe, ob die Ressource existiert und die erstellende Person noch Zugriff hat.

Best Practices

Erstelle einen Key pro Integration oder Umgebung.
Benenne Keys nach Job und Umgebung, nicht nach Person.
Nutze Lesen oder Schreiben statt Vollzugriff, wenn Löschen nicht nötig ist.
Nutze Team-Scope, wenn eine Automatisierung zu einem einzelnen Team gehört.
Speichere Keys in einem Secret-Manager.
Widerrufe nicht mehr genutzte Keys sofort.

​Key erstellen

​API-Key-Anfragen testen

​Key verwenden

​Berechtigungsstufen

​Scope-Referenz

​Workspace- und Team-Scope

​Ablauf und Rotation

​Häufige Fehler

​Best Practices

Key erstellen

API-Key-Anfragen testen

Key verwenden

Berechtigungsstufen

Scope-Referenz

Workspace- und Team-Scope

Ablauf und Rotation

Häufige Fehler

Best Practices