Uwierzytelnianie

Uwierzytelnianie kluczem API

Wszystkie żądania API muszą zawierać klucz API w nagłówku Authorizationprzy użyciu schematu tokenu Bearer:

Authorization: Bearer flp_your_api_key_here

Tworzenie kluczy API

Przejdź do Konto → Klucze API w panelu FloopFloop, aby tworzyć klucze API i zarządzać nimi.

• Każde konto może mieć do 5 aktywnych kluczy API
• Klucze są wyświetlane tylko raz podczas tworzenia — przechowuj je w bezpiecznym miejscu
• Klucze można unieważnić w dowolnym momencie z poziomu panelu
• Wszystkie klucze zaczynają się od prefiksu flp_

Bezpieczeństwo kluczy

• Nigdy nie udostępniaj kluczy API ani nie umieszczaj ich w systemie kontroli wersji
• Używaj zmiennych środowiskowych do przechowywania kluczy w aplikacjach
• Regularnie rotuj klucze i unieważniaj nieużywane
• Każdy klucz ma własny zasobnik limitów szybkości

Limity szybkości

Punkty końcowe API mają następujące limity szybkości na klucz API:

Informacje o limitach szybkości są zawarte w nagłówkach odpowiedzi:X-RateLimit-Remaining i X-RateLimit-Reset.

Weryfikacja uwierzytelniania

GET /api/v1/user/me

Użyj tego punktu końcowego, aby potwierdzić, że klucz API jest prawidłowy. Zwraca profil uwierzytelnionego użytkownika i jest standardowym wywołaniem “przetestuj swoje uwierzytelnianie” używanym przez wszystkie oficjalne SDK oraz przez floop whoami w CLI.

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

Odpowiedź (200):

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "role": "user",
    "source": "api_key"
  }
}

• role — "user" dla normalnych kont, "admin" dla pracowników platformy.
• source — sposób uwierzytelnienia żądania. "api_key" dla poświadczeń programatycznych, "cli_token" dla autoryzowanego przez urządzenie przepływu CLI.

Odpowiedź 401 UNAUTHORIZED oznacza, że klucz brakuje, został unieważniony lub jest nieprawidłowy. Odpowiedź 403 FORBIDDENoznacza, że konto istnieje, ale nie posiada planu Business wymaganego do dostępu do API (zob. Wymagania w przeglądzie API).

Programatyczne zarządzanie kluczami API

Większość użytkowników tworzy klucze z panelu, ale ta sama funkcjonalność jest dostępna przez API dla scenariuszy orkiestracji — rotacja klucza z zadania CI, listowanie kluczy w celu audytu użycia lub unieważnienie ujawnionego klucza bez konieczności korzystania z interfejsu. Odpowiada to temu, co robi floop keys list/create/removew CLI.

Listowanie kluczy API

GET /api/v1/api-keys

Zwraca metadane dla każdego aktywnego (nieunieważnionego) klucza na koncie. Materiał klucza w postaci zwykłego tekstu nigdy nie jest zwracany — tylko keyPrefix (pierwsze 8 znaków szesnastkowych klucza, poprzedzone 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"
      }
    ]
  }
}

Tworzenie klucza API

POST /api/v1/api-keys

{
  "name": "ci-deploy"    // required, 1-100 chars
}

Odpowiedź (201):

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

rawKey jest wyświetlany tylko raz— kolejne odczyty zwracają wyłącznie keyPrefix. Zapisz go natychmiast. Każde konto ma limit 5 aktywnych kluczy; po przekroczeniu limitu żądanie zwraca409 LIMIT_EXCEEDED— najpierw unieważnij nieużywany klucz.

Tworzenie klucza wymaga planu Business. Żądanie z konta bez planu Business zwraca 403 FORBIDDEN z komunikatem “Creating API keys requires the Business plan”. Administratorzy platformy omijają tę blokadę.

Unieważnianie klucza API

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

Podaj id klucza (np.key_xyz) jako parametr ścieżki. Klucz jest unieważniany natychmiast — żądania będące w trakcie przetwarzania przez worker mogą zostać ukończone, ale żadne nowe żądania nie będą uwierzytelnione.

Odpowiedź (200):

{ "data": { "success": true } }

• Samounieważnianie jest zablokowane. Wywołanie DELETE tym samym kluczem, który wysyła żądanie, zwraca400 VALIDATION_ERROR— zapobiega to odcięciu się CLI w trakcie wywołania. Użyj innego klucza lub unieważnij z panelu.
• Nieznane lub już unieważnione klucze zwracają404 NOT_FOUND.

Oficjalne SDK akceptują zarówno id, jak i nazwę klucza w swoich pomocnikach apiKeys.remove(), rozwiązując nazwę → id po stronie klienta przez wywołanie listy. Sam API akceptuje tylko id.

Unieważnionego klucza nie można przywrócić; utwórz nowy, aby go zastąpić. Unieważnienie jest rejestrowane w dzienniku audytu widocznym w Konto → Klucze API.