Zum Hauptinhalt springen
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.
1

API-Key-Einstellungen öffnen

Gehe in deinem Workspace zu Einstellungen → API-Keys.
2

Key benennen

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

Zielbereich wählen

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

Berechtigungen auswählen

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

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 nutzt standardmässig https://pharen.app als baseUrl. Du kannst baseUrl bei jedem Endpoint ändern, wenn du gegen eine andere Umgebung testen möchtest.

​
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.
StufeEnthaltene ScopesGeeignet für
KeineKeine ScopesKeys, die keinen Zugriff auf diese Ressource haben sollen.
Lesenresource:readReports, Sync-Jobs, Exporte und read-only Dashboards.
Schreibenresource:read, resource:create, resource:updateImporte und bidirektionale Syncs, die keine Daten löschen sollen.
Vollzugriffresource:read, resource:create, resource:update, resource:deleteAdministrative Jobs, die Daten entfernen dürfen.
Workflows und Agents nutzen gezielte Ausführungsrechte.
RessourceLesenAusführen
Workflowsworkflows:readworkflows:read, workflows:run
Agentsagents:readagents:read, agents:run

​
Scope-Referenz

ScopeErlaubt
lists:readGespeicherte Listendaten, Felder, Zeilen, Zellen und Ansichten lesen.
lists:createNeue Listen erstellen.
lists:updateListen, Felder, Zeilen, Zellen, Ansichten und Freigabedaten aktualisieren.
lists:deleteListen oder Listeneinträge löschen.
docs:readDokumente, Sammlungen, Versionen, Dateien und Zugriffsmetadaten lesen.
docs:createDokumente und Sammlungen erstellen.
docs:updateDokumente, Sammlungen, Dateien, Freigaben, Versionen und Aktivitätslinks aktualisieren.
docs:deleteDokumente und Sammlungen löschen oder wiederherstellen.
calendar:readKalenderquellen, Ereignisse und Exporte lesen.
calendar:createKalenderquellen, Ereignisse und Importe erstellen.
calendar:updateKalenderquellen und Ereignisse aktualisieren.
calendar:deleteKalenderquellen und Ereignisse löschen.
workflows:readWorkflow-Definitionen, Versionen, Validierungsergebnisse und Ausführungspläne lesen.
workflows:runWorkflows ausführen. Streaming-Ausführung benötigt zusätzlich Streaming-Zugriff auf dem Key.
agents:readAgents, Katalogdaten, Tools, Unterhaltungen und Logs lesen.
agents:runAgent-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.
  1. Erstelle einen Ersatz-Key mit denselben oder engeren Scopes.
  2. Hinterlege den neuen Key im Secret-Manager.
  3. Prüfe, ob die Integration mit dem neuen Key funktioniert.
  4. Widerrufe den alten Key unter Einstellungen → API-Keys.

​
Häufige Fehler

StatusBedeutungLösung
401 UnauthorizedDer Key fehlt, ist fehlerhaft, abgelaufen, widerrufen oder ungültig.Prüfe Header, Secret-Wert und Key-Status.
403 ForbiddenDer 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 FoundDie 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.