Zum Inhalt springen

Erste Schritte

Authentifizierung

Wie ein Schlüssel einen Workspace identifiziert, was er erlaubt und wie Sie ihn schützen.

Ein Schlüssel identifiziert einen Workspace und ein Mitglied und trägt die Liste dessen, was er darf. Diese Seite behandelt, wie Sie ihn senden, was er erlaubt, welche Limits gelten und wie Sie ihn schützen.

Schlüssel senden#

Jede Route erwartet den Schlüssel im Header Authorization. Ausnahmen sind GET/api/v1 und GET/api/v1/openapi.json, die öffentlich sind:

HTTP
Authorization: Bearer piq_live_…

Der Header x-api-key: piq_live_… wird für Clients akzeptiert, die Authorization nicht setzen können.

Ein Schlüssel beginnt mit piq_live_, gefolgt von 38 Zeichen. Die Einstellungen zeigen die ersten 6 Zeichen nach dem Präfix, damit Sie ihn wiedererkennen. Der Rest wird nie wieder angezeigt.

Wofür ein Schlüssel steht#

Ein Schlüssel handelt im Namen des Mitglieds, das ihn erstellt hat, in dessen Workspace und mit dessen Rolle. Die Regeln des Dashboards gelten unverändert: Ein Schlüssel sieht nie einen anderen Workspace und funktioniert nicht mehr, sobald sein Ersteller den Workspace verlässt.

Nur Owner und Admins erstellen Schlüssel, in Einstellungen → API und MCP. Ein Workspace hat höchstens 25 aktive Schlüssel.

Scopes#

Ein Scope öffnet eine Familie von Tools. Jedes Tool verlangt seinen eigenen, angegeben im Katalog.

ScopeWas er öffnet
readKorpus und Workspace lesen: Quellen, Items, Themen, Signale, Entitäten, Boards, Tabellen, Upwork-Pipeline.
exploreWeb, soziale Netzwerke, Register und Archive live lesen. Verbraucht Credits des Workspace.
writeIm Workspace schreiben: Boards, Tabellen, verfolgte Entitäten, Watch-Verträge, Profil, Upwork-Entwürfe.
actAuf die Beobachtung einwirken: eine Quelle abonnieren oder kündigen, eine Signalregel setzen, eine Recherche starten, einer Kampagne folgen.
agentsDie Agenten Piqline, Requête, Facebook, LinkedIn, Upwork und Onboarding antworten lassen. Verbraucht Credits des Workspace.

Wählen Sie das Minimum. read genügt, um den Korpus zu lesen. Fügen Sie agents hinzu, damit ein Agent antwortet. Ein Agentenlauf mit Ihrem Schlüssel nutzt nur Tools, die der Schlüssel auch selbst aufrufen könnte.

Ablauf und Widerruf#

Ein Schlüssel kann unbegrenzt gültig sein oder nach 90 Tagen oder einem Jahr ablaufen. Zum Widerrufen öffnen Sie Einstellungen → API und MCP, klicken auf Widerrufen und dann auf Schlüssel widerrufen. Aufrufe mit diesem Schlüssel erhalten innerhalb einer Minute ein 401.

Grenzwerte#

Limit pro SchlüsselStandardwertBei Überschreitung
Anfragen pro Minute120429 rate_limited, mit Retry-After
Agenten-Turns pro Minute10429 rate_limited, mit Retry-After
Anfragen pro Tag20.000429 quota_exceeded

Jede Antwort enthält RateLimit-Limit (die pro Minute erlaubte Lastspitze) und RateLimit-Remaining (was übrig ist). Das Limit pro Minute bremst Lastspitzen: Es gilt pro Serverinstanz und lässt gegebenenfalls etwas mehr durch als der genannte Wert. GET/api/v1/workspace liefert die Limits des Schlüssels und die Zahl der heutigen Anfragen.

Nutzung und Verlauf#

Einstellungen → API und MCP zeigt die Nutzung der letzten 30 Tage pro Tool und pro Agent sowie den Verlauf jeder Anfrage: Zeit, Operation, Status, Dauer, Fehler, Ausschnitt der Eingabe, Client und Herkunftsnetz. Der Verlauf wird 30 Tage aufbewahrt.

Er enthält weder den Schlüssel noch den vollständigen Anfragetext: Der Ausschnitt der Eingabe wird bei 300 Zeichen abgeschnitten, Felder, die nach Geheimnissen aussehen (Passwort, Token, Schlüssel), werden maskiert, und nur das Netzpräfix (/24 bei IPv4, /48 bei IPv6) wird gespeichert, nie die vollständige IP-Adresse.

Schlüssel schützen#

  • Bewahren Sie ihn in einem Secrets-Manager oder einer Umgebungsvariable auf. Nie in einem Repository, auf einer Webseite oder in einer mobilen App.
  • Erstellen Sie einen Schlüssel pro Verwendung (ein Skript, ein Agent, ein Kollege) und geben Sie ihm einen Namen, den Sie wiedererkennen: So widerrufen Sie einen, ohne die anderen anzufassen.
  • Geben Sie Testschlüsseln ein Ablaufdatum.
  • Widerrufen Sie einen offengelegten Schlüssel sofort. Piqline speichert nur seinen Fingerabdruck: Es kann Ihnen den Schlüssel nicht zurückgeben, nur einen neuen erstellen.
  • Ein Schlüssel behält die Rechte seines Erstellers und endet, wenn dieser das Team verlässt. Erstellen Sie ihn für den dauerhaften Einsatz über ein Konto, das nur für die Integration vorgesehen ist.

Eine Frage zur API oder ein Fehler auf dieser Seite? Schreiben Sie uns.