Zaloguj się

Uwierzytelnianie

Uwierzytelnianie API, cykl życia sesji i najlepsze praktyki bezpieczeństwa

Cliqer uwierzytelnia za pomocą ciasteczka sesji httpOnly (session_token), tworzonego przez POST /api/auth/login. Przeglądarki wysyłają je automatycznie przy każdym żądaniu, a narzędzia server-to-server przechowują je w magazynie ciasteczek (cookie jar). Zespoły Studio 8K i Enterprise mogą dodatkowo tworzyć klucze API do dostępu server-to-server, wysyłane jako Authorization: Bearer cliqer_<key>, zobacz Uwierzytelnianie kluczem API poniżej.

Model sesji

PoświadczenieGdzie się znajdujeJak je uzyskać
Ciasteczko sesji (session_token)Ciasteczko httpOnly i Secure na Twoim hoście CliqerUstawiane przez POST /api/auth/login, automatycznie rotowane przez serwer

Ciasteczko ma flagę HttpOnly, więc nie da się go odczytać z JavaScriptu. Jego czas życia odpowiada TTL sesji na serwerze i jest odnawiany w tle za każdym razem, gdy wywołujesz GET /api/auth/me. Nie ma osobnego endpointu odświeżania: aby długo działający klient zachowywał się poprawnie, wystarczy okresowo wywoływać GET /api/auth/me.

Cykl życia sesji

Korzystanie z sesji

Przeglądarki dołączają ciasteczko automatycznie. W klientach server-to-server zapisz ciasteczko ustawione przez odpowiedź na logowanie i wysyłaj je w kolejnych żądaniach:

# Save the session cookie on login, then reuse it
curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","password":"your_password"}'

curl -X GET "$BASE_URL/api/auth/me" -b cookies.txt

Uwierzytelnianie kluczem API

Zespoły Studio 8K i Enterprise mogą tworzyć długoterminowe klucze API do dostępu server-to-server, co pozwala nie przechowywać danych logowania użytkownika. Tworzysz je i unieważniasz w panelu, w sekcji Zespół → Klucze API (/dash/team/api-keys). Do utworzenia klucza potrzebny jest właściciel zespołu (lub rola niestandardowa z uprawnieniem do kluczy API). Zarządzanie kluczami jest dostępne wyłącznie w planach Studio 8K i Enterprise.

Strona Klucze API w panelu, w sekcji Zespół na pasku bocznym, z przyciskiem Utwórz klucz i informacją o wysyłaniu klucza jako tokenu Bearer

Klucz jest wyświetlany tylko raz, podczas tworzenia, w formacie cliqer_<prefix>_<secret>. Przechowuj go w bezpiecznym miejscu: nie da się go odzyskać, więc jeśli go zgubisz, unieważnij go i utwórz nowy. Wysyłaj go jako token Bearer do dowolnego endpointu REST, który akceptuje sesję:

curl -X GET "$BASE_URL/api/licenses/status?license_key=YOUR_LICENSE_KEY" \
  -H "Authorization: Bearer cliqer_ab12cd34_your_secret_here"

Klucze API działają tylko z endpointami REST. WebSocket, łącznie ze sterowaniem slajdami, wymaga tokenu sesji.

Klucz uwierzytelnia jako użytkownik, który go utworzył, w zakresie zespołu i planu tego użytkownika. Unieważniony lub nieznany klucz zwraca 401, dokładnie tak jak brak sesji. Endpointy dostępne tylko dla administratorów zawsze odrzucają klucze API z kodem 403. Klucze podlegają tym samym limitom żądań co żądania z sesją.

Traktuj klucz API jak hasło. Każdy, kto go posiada, może działać jako Twoje konto na udokumentowanych endpointach, dopóki go nie unieważnisz.

Logowanie

Wymień dane logowania użytkownika na sesję. Po udanym logowaniu odpowiedź ustawia ciasteczko session_token.

Endpoint: POST /api/auth/login

ParametrTypWymaganyOpis
emailstringTakAdres e-mail użytkownika (akceptowana jest też nazwa użytkownika WordPress)
passwordstringTakHasło użytkownika
otpstringNieKod TOTP, gdy konto korzysta z aplikacji uwierzytelniającej
email_otpstringNiePIN wysłany e-mailem, gdy konto korzysta z 2FA przez e-mail
curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","password":"your_password"}'

Odpowiedź (sukces): ustawia ciasteczko session_token i zwraca metadane sesji.

{
  "data": {
    "expires": 604800000
  }
}

Odpowiedź (wymagane 2FA): sygnał sterujący przepływem z kodem 200, a nie błąd. Wyślij ponownie POST /api/auth/login z tymi samymi danymi logowania oraz polem otp (aplikacja uwierzytelniająca) lub email_otp (PIN z e-maila).

{
  "requires_otp": true,
  "method": "totp",
  "email_sent": false
}

method przyjmuje jedną z wartości: totp, email lub both. W przypadku email serwer wysyła PIN e-mailem, a email_sent informuje, czy ta wiadomość została wysłana. Konto z metodą both loguje się kodem z aplikacji uwierzytelniającej (otp). PIN wysłany e-mailem nie jest dla niego składnikiem logowania.

Nieprawidłowe dane logowania zwracają 401, podobnie jak błędny lub wygasły kod TOTP. Błędny lub wygasły PIN z e-maila również zwraca 401 z tym samym komunikatem co błędne hasło. Członek organizacji, która wymaga logowania jednokrotnego, otrzymuje 403 i musi zalogować się przez SSO (zobacz FAQ dotyczące SSO).

Rotacja sesji

Nie ma osobnego endpointu odświeżania. Serwer rotuje ciasteczko session_token za Ciebie: gdy sesja zbliża się do wygaśnięcia, GET /api/auth/me zwraca razem z profilem nowy nagłówek Set-Cookie. Klient, który przechowuje ciasteczka i okresowo wywołuje GET /api/auth/me, pozostaje zalogowany bezterminowo, bez żadnej dodatkowej pracy.


Bieżący użytkownik

Zwraca profil uwierzytelnionego użytkownika lub { "data": null }, gdy nie ma ważnej sesji (obsługuje wywołania anonimowe i nigdy nie zwraca 401).

Endpoint: GET /api/auth/me

curl -X GET "$BASE_URL/api/auth/me" -b cookies.txt

Odpowiedź:

{
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "role": "uuid",
    "tfa_method": "none",
    "is_admin": false
  }
}

Wylogowanie

Kończy sesję powiązaną z bieżącym ciasteczkiem i usuwa je z przeglądarki.

Endpoint: POST /api/auth/logout

curl -X POST "$BASE_URL/api/auth/logout" -b cookies.txt -c cookies.txt

Odpowiedź:

{
  "success": true
}

Najlepsze praktyki bezpieczeństwa

Zalecane środki bezpieczeństwa
  1. Używaj wyłącznie HTTPS: ciasteczko sesji ma flagę Secure, a wszystkie żądania muszą korzystać z TLS 1.2+.
  2. Nigdy nie odczytuj ciasteczka z JavaScriptu: ma flagę HttpOnly celowo i niech tak zostanie.
  3. Odświeżaj z wyprzedzeniem: w długo otwartych kartach wywołuj GET /api/auth/me przed wygaśnięciem sesji, a serwer sam zrotuje ciasteczko.
  4. Wyloguj się, aby unieważnić sesję: POST /api/auth/logout natychmiast kończy sesję po stronie serwera.
  5. Przechowuj dane logowania, nie sesje: integracje server-to-server powinny trzymać dane logowania w menedżerze sekretów i na nowo nawiązywać sesję. Nigdy nie zapisuj ciasteczka w kodzie źródłowym.
Funkcje bezpieczeństwa dla firm opisuje Przegląd bezpieczeństwa.