API-Referenz

Authentifizierung

So erstellen und verwenden Sie API-Schlüssel zur Authentifizierung mit der FloopFloop-API.

Zuletzt aktualisiert:

API-Schlüssel-Authentifizierung

Alle API-Anfragen müssen Ihren API-Schlüssel im Authorization-Header nach dem Bearer-Token-Schema enthalten:

Authorization: Bearer flp_your_api_key_here

API-Schlüssel erstellen

Navigieren Sie in Ihrem FloopFloop-Dashboard zu Account → API Keys, um API-Schlüssel zu erstellen und zu verwalten.

  • Jedes Konto kann bis zu 5 aktive API-Schlüssel haben
  • Schlüssel werden nur einmal bei der Erstellung angezeigt — bewahren Sie sie sicher auf
  • Schlüssel können jederzeit über das Dashboard widerrufen werden
  • Alle Schlüssel beginnen mit dem Präfix flp_

Schlüsselsicherheit

  • Teilen Sie Ihre API-Schlüssel niemals oder übertragen Sie sie in die Versionskontrolle
  • Verwenden Sie Umgebungsvariablen, um Schlüssel in Ihren Anwendungen zu speichern
  • Rotieren Sie Schlüssel regelmäßig und widerrufen Sie ungenutzte Schlüssel
  • Jeder Schlüssel hat seinen eigenen Rate-Limit-Bucket

Rate Limits

API-Endpunkte haben die folgenden Rate Limits pro API-Schlüssel:

OperationLimitWindow
Leseoperationen (GET)120 requests1 minute
Schreiboperationen (POST/PATCH/DELETE)30 requests1 minute
Deploy/Rollback5 requests1 hour
Projekterstellung/Clone10 requests1 hour

Rate-Limit-Informationen sind in den Antwortheadern enthalten:X-RateLimit-Remaining und X-RateLimit-Reset.

Authentifizierung überprüfen

GET /api/v1/user/me

Verwenden Sie diesen Endpunkt, um zu bestätigen, dass Ihr API-Schlüssel gültig ist. Er gibt das Profil des authentifizierten Benutzers zurück und ist der standardmäßige “Authentifizierung testen”-Aufruf, der von jedem offiziellen SDK und von floop whoami in der CLI verwendet wird.

curl https://floopfloop.com/api/v1/user/me \
  -H "Authorization: Bearer flp_your_api_key_here"

Response (200):

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "role": "user",
    "source": "api_key"
  }
}
  • role — "user" für normale Konten, "admin" für Plattformmitarbeiter.
  • source — wie die Anfrage authentifiziert wurde. "api_key" für programmgesteuerte Anmeldeinformationen, "cli_token" für den geräteautoriserten CLI-Ablauf.

Ein 401 UNAUTHORIZED hier bedeutet, dass der Schlüssel fehlt, widerrufen oder fehlerhaft ist. Ein 403 FORBIDDEN bedeutet, dass das Konto existiert, aber nicht den Business-Plan besitzt, der den API-Zugang ermöglicht (siehe Voraussetzungen in der API-Übersicht).

Programmgesteuerte API-Schlüsselverwaltung

Die meisten Benutzer erstellen Schlüssel über das Dashboard, aber dieselbe Oberfläche ist auch über die API für Orchestrierungsszenarien verfügbar — einen Schlüssel aus einem CI-Job rotieren, Schlüssel zur Nutzungsüberprüfung auflisten oder einen kompromittierten Schlüssel ohne UI-Umweg widerrufen. Dies spiegelt wider, was floop keys list/create/remove in der CLI tut.

API-Schlüssel auflisten

GET /api/v1/api-keys

Gibt Metadaten für jeden aktiven (nicht widerrufenen) Schlüssel des Kontos zurück. Klartextschlüsselmaterial wird niemals zurückgegeben — nur das keyPrefix (die ersten 8 Hex-Zeichen des Schlüssels, mit dem Präfix flp_).

{
  "data": {
    "keys": [
      {
        "id": "key_abc",
        "name": "ci-deploy",
        "keyPrefix": "flp_a1b2c3d4",
        "scopes": null,
        "lastUsedAt": "2026-04-24T18:30:00Z",
        "createdAt": "2026-04-01T12:00:00Z"
      }
    ]
  }
}

API-Schlüssel erstellen

POST /api/v1/api-keys
{
  "name": "ci-deploy"    // required, 1-100 chars
}

Response (201):

{
  "data": {
    "id": "key_xyz",
    "rawKey": "flp_a1b2c3d4…full-40-hex…",
    "keyPrefix": "flp_a1b2c3d4"
  }
}

Der rawKey wird nur einmal angezeigt— nachfolgende Abfragen geben nur das keyPrefix zurück. Speichern Sie ihn sofort. Jedes Konto ist auf 5 aktive Schlüssel begrenzt; wenn Sie das Limit erreichen, gibt die Anfrage409 LIMIT_EXCEEDEDzurück — widerrufen Sie zuerst einen ungenutzten Schlüssel.

Das Erstellen eines Schlüssels erfordert den Business-Plan. Eine Anfrage von einem Nicht-Business-Konto gibt 403 FORBIDDEN mit der Meldung “Creating API keys requires the Business plan” zurück. Plattformadministratoren umgehen diese Beschränkung.

API-Schlüssel widerrufen

DELETE /api/v1/api-keys/{keyId}

Übergeben Sie die iddes Schlüssels (z. B.key_xyz) als Pfadparameter. Der Schlüssel wird sofort ungültig gemacht — bereits auf einem Worker laufende Anfragen können abgeschlossen werden, aber keine neuen Anfragen werden authentifiziert.

Response (200):

{ "data": { "success": true } }
  • Selbst-Widerruf ist gesperrt. Der Aufruf von DELETE mit demselben Schlüssel, der die Anfrage stellt, gibt400 VALIDATION_ERRORzurück — dies verhindert, dass die CLI sich selbst während eines Aufrufs abschneidet. Verwenden Sie einen anderen Schlüssel oder widerrufen Sie ihn über das Dashboard.
  • Unbekannte oder bereits widerrufene Schlüssel geben404 NOT_FOUND zurück.

Die offiziellen SDKs akzeptieren entweder eine ID oder einen Schlüsselnamen in ihrenapiKeys.remove()-Hilfsmethoden und lösen den Namen → ID clientseitig über einen Listenaufruf auf. Die API selbst akzeptiert nur die ID.

Ein widerrufener Schlüssel kann nicht wiederhergestellt werden; erstellen Sie einen neuen, um ihn zu ersetzen. Der Widerruf wird im Audit-Log auf Account → API Keys aufgezeichnet.

ZurückAPI-ÜbersichtWeiterProjekte