Skip to main content

Klucze API - Zarządzanie i bezpieczeństwo

Klucze API pozwalają na programistyczny dostęp do platformy Mailist. Automatyzuj tworzenie kontaktów, wysyłkę kampanii i zarządzanie danymi z własnych aplikacji.

Czym jest klucz API?

Klucz API to unikalny identyfikator używany do uwierzytelniania żądań do REST API Mailist. Działa jak hasło - pozwala Twojej aplikacji na dostęp do danych i funkcji platformy.
Bezpieczeństwo: Traktuj klucze API jak hasła. Nie udostępniaj ich publicznie ani nie commituj do repozytoriów Git.

Dostęp do kluczy API

1

Otwórz sekcję Integracje

W menu głównym przejdź do Integracje API
2

Przegląd kluczy

Zobaczysz dashboard z:
  • Wszystkie klucze (całkowita liczba)
  • Aktywne klucze
  • Nieaktywne klucze (odwołane/wygasłe)
  • Całkowite żądania API (z wszystkich kluczy)

Tworzenie nowego klucza API

1

Kliknij 'Utwórz nowy klucz'

Przycisk w prawym górnym rogu sekcji Integracje
2

Wypełnij formularz

Podstawowe informacje

Dobra nazwa: Opisz gdzie i jak klucz będzie używany. To pomoże Ci później zidentyfikować klucze.Przykłady:
  • “Landing Page - Newsletter signup”
  • “Mobile App - iOS Production”
  • “Webhook - Abandoned Cart”
  • “Internal CRM Integration”

Wybór uprawnień

Zaznacz uprawnienia, których potrzebuje Twoja integracja:
Principle of Least Privilege: Nadawaj tylko te uprawnienia, których faktycznie potrzebuje Twoja integracja.Przykład: Formularz zapisu do newslettera potrzebuje tylko contacts.write + lists.read, nie wymaga campaigns.send.
3

Utwórz klucz

Kliknij Utwórz klucz API
4

Skopiuj klucz

WAŻNE! To jedyny raz, kiedy zobaczysz pełny klucz. Skopiuj go i przechowuj bezpiecznie.
Modal wyświetli:
Kliknij Kopiuj i zapisz klucz w bezpiecznym miejscu (np. password manager).

Używanie klucza API

Uwierzytelnianie

Dodaj klucz do nagłówka Authorization jako Bearer token:

Przykłady użycia

Wymagane uprawnienie: contacts.write
Wymagane uprawnienie: campaigns.read
Wymagane uprawnienie: contacts.write
Wymagane uprawnienia: contacts.write, automation.write

Zarządzanie kluczami

Przegląd kluczy

W tabeli kluczy API zobaczysz:

Filtrowanie kluczy

Szukaj po:
  • Nazwie klucza
  • Fragmencie klucza API

Akcje na kluczach

Kiedy używać: Tymczasowe wyłączenie klucza bez usuwaniaJak:
  1. Menu akcji → Dezaktywuj (lub Aktywuj)
  2. Status zmienia się na “Odwołany”
  3. Wszystkie żądania z tym kluczem będą odrzucane (HTTP 401)
Użycie:
  • Debugowanie integracji
  • Rotacja kluczy (wyłącz stary, włącz nowy)
  • Podejrzenie compromisu bezpieczeństwa
Co robi: Generuje nowy klucz, stary przestaje działaćKiedy używać:
  • Klucz został przypadkowo udostępniony publicznie
  • Regularny rotation (best practice: co 90 dni)
  • Zmiana środowiska (dev → production)
Proces:
  1. Menu akcji → Wygeneruj ponownie
  2. Potwierdź: “Stary klucz przestanie działać”
  3. Skopiuj nowy klucz (pokazany raz!)
  4. Zaktualizuj klucz w swojej aplikacji
Uwaga: Stary klucz natychmiast przestaje działać. Aplikacja używająca starego klucza zacznie dostawać błędy 401.Strategia zero-downtime:
  1. Stwórz nowy klucz (osobny, nie regeneruj)
  2. Wdróż aplikację z nowym kluczem
  3. Poczekaj kilka dni (upewnij się że stary nie jest używany)
  4. Usuń stary klucz
Kopiuje pełny klucz API do schowka.Uwaga: Klucze są zamaskowane w interfejsie (ml_prod_a1b2...******), ale przycisk kopiuje pełny klucz.
Permanentnie dezaktywuje klucz (nie można cofnąć)Różnica vs dezaktywacja:
  • Dezaktywacja: Można ponownie aktywować
  • Odwołanie: Nie można aktywować (tylko usunąć)
Użycie: Kompromis bezpieczeństwa - klucz wyciekł publicznie
Permanentnie usuwa klucz z systemu.
Nieodwracalne! Klucz znika z listy, wszystkie statystyki zostają usunięte.
Kiedy usuwać:
  • Projekt został zamknięty
  • Integracja nie jest już używana
  • Czyszczenie starych/testowych kluczy

Statystyki i monitoring

Top Endpoints

Platforma pokazuje najpopularniejsze endpointy API używane przez Twoje klucze:
Użycie:
  • Zidentyfikuj najczęściej używane endpointy
  • Optymalizuj rate limiting
  • Znajdź potencjalne bottlenecki

Per-Key Statistics

Każdy klucz pokazuje:
  • Całkowite żądania: Suma wszystkich wywołań API
  • Ostatnie użycie: Kiedy klucz był ostatnio używany (pomaga znaleźć nieużywane klucze)

Bezpieczeństwo - Best Practices

Przechowywanie kluczy

✅ Dobrze:
  • Zmienne środowiskowe (.env file, nie commitowane)
  • Secrets manager (AWS Secrets, Azure Key Vault)
  • Password manager (1Password, LastPass)
❌ Źle:
  • Hardcoded w kodzie
  • Commitowane do Git
  • Przesyłane plaintext emailem
  • Zapisane w logs

Rotacja kluczy

Zalecane: Co 90 dniAutomatyzacja:

Minimalne uprawnienia

Nadawaj tylko te uprawnienia, których potrzebujesz:

Monitoring

Regularnie sprawdzaj:
  • Nieużywane klucze (ostatnie użycie > 90 dni)
  • Nieoczekiwane spike’i w requestach
  • 401 errors (potencjalna próba włamania)
Akcja: Usuń nieużywane klucze

Rate Limiting

Mailist ma limity żądań API: Co się stanie przy przekroczeniu:
Jak obsłużyć:

Błędy uwierzytelniania

Przyczyny:
  • Brak nagłówka Authorization
  • Nieprawidłowy format (brak “Bearer ”)
  • Klucz odwołany/wygasły
  • Klucz nie istnieje (literówka)
Rozwiązanie:
Przyczyny:
  • Klucz nie ma wymaganego uprawnienia
  • Próba dostępu do zasobu poza zakresem uprawnień
Rozwiązanie:
  1. Sprawdź uprawnienia klucza w Integracje → [Twój klucz]
  2. Edytuj klucz → Dodaj brakujące uprawnienie
  3. LUB stwórz nowy klucz z odpowiednimi uprawnieniami
Rozwiązanie:
  • Implementuj exponential backoff
  • Cache’uj odpowiedzi gdzie możliwe
  • Batch requests (np. bulk import zamiast pojedynczych)
  • Upgrade plan dla wyższych limitów

Środowiska: Development vs Production

Zalecane jest używanie osobnych kluczy dla różnych środowisk:
Przechowywanie:

FAQ

Zależy od planu:
  • Free: 2 klucze
  • Starter: 5 kluczy
  • Business: 20 kluczy
  • Enterprise: Nieograniczone
Strategie przy limicie:
  • Jeden klucz per aplikacja/środowisko
  • Usuń nieużywane klucze
  • Grupuj podobne integracje (jeśli bezpieczne)
Klucze są pokazane tylko raz przy tworzeniu.Jeśli zgubiłeś:
  1. Nie możesz go odzyskać - klucze są haszowane w bazie
  2. Wygeneruj nowy klucz (regeneruj istniejący lub stwórz nowy)
  3. Zaktualizuj aplikację z nowym kluczem
  4. Usuń stary klucz
Zapobieganie:
  • Zapisuj klucze w password managerze od razu
  • Używaj .env files dla lokalnego developmentu
  • Dokumentuj gdzie każdy klucz jest używany
Nie, klucze API nie wygasają automatycznie (chyba że ręcznie ustawisz datę wygaśnięcia w przyszłości).Best practice: Rotuj klucze co 90 dni dla bezpieczeństwa.
Tak, ale niezalecane ze względów bezpieczeństwa.Lepiej:
  • Osobny klucz per środowisko (dev, staging, prod)
  • Osobny klucz per aplikacja (jeśli masz wiele)
Dlaczego:
  • Łatwiejszy audit (wiesz, która aplikacja wywołała API)
  • Łatwiejsza rotacja (jeden kompromis nie wpływa na inne)
  • Lepszy monitoring (per-key statistics)

Następne kroki

Dokumentacja REST API

Pełna dokumentacja endpointów API

Przykłady integracji

Gotowe przykłady dla popularnych przypadków użycia

Webhooks

Użyj custom events do trigger automatyzacji

Billing & Limity

Sprawdź limity API w swoim planie

Bezpieczeństwo - Zgłaszanie problemów

Jeśli znajdziesz lukę bezpieczeństwa lub podejrzewasz kompromis klucza:

Security Team

Email: security@mailist.comZgłoś:
  • Opis problemu
  • Kompromitowany klucz (jeśli dotyczy)
  • Timestamp incydentu
Odpowiedź: W ciągu 24 godzin