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:
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.
| Scope | Was er öffnet |
|---|---|
read | Korpus und Workspace lesen: Quellen, Items, Themen, Signale, Entitäten, Boards, Tabellen, Upwork-Pipeline. |
explore | Web, soziale Netzwerke, Register und Archive live lesen. Verbraucht Credits des Workspace. |
write | Im Workspace schreiben: Boards, Tabellen, verfolgte Entitäten, Watch-Verträge, Profil, Upwork-Entwürfe. |
act | Auf die Beobachtung einwirken: eine Quelle abonnieren oder kündigen, eine Signalregel setzen, eine Recherche starten, einer Kampagne folgen. |
agents | Die 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üssel | Standardwert | Bei Überschreitung |
|---|---|---|
| Anfragen pro Minute | 120 | 429 rate_limited, mit Retry-After |
| Agenten-Turns pro Minute | 10 | 429 rate_limited, mit Retry-After |
| Anfragen pro Tag | 20.000 | 429 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.