# Authentifizierung

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

Source: https://piqline.com/de/docs/api/authentication

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](/settings/api). 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](/de/docs/api/tools#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](/settings/api), 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.
