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.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
Wybór uprawnień
Zaznacz uprawnienia, których potrzebuje Twoja integracja:| Uprawnienie | Opis | Użycie |
|---|---|---|
| contacts.read | Odczyt kontaktów | Pobieranie listy kontaktów, szczegóły kontaktu |
| contacts.write | Tworzenie/edycja kontaktów | Dodawanie nowych subskrybentów, aktualizacja danych |
| contacts.delete | Usuwanie kontaktów | Permanentne usuwanie kontaktów |
| lists.read | Odczyt list | Pobieranie listy wszystkich list |
| lists.write | Tworzenie/edycja list | Tworzenie nowych list, dodawanie kontaktów do list |
| campaigns.read | Odczyt kampanii | Pobieranie statystyk kampanii |
| campaigns.write | Tworzenie/edycja kampanii | Tworzenie i edycja kampanii |
| campaigns.send | Wysyłka kampanii | Uruchamianie wysyłki kampanii |
| automation.read | Odczyt automatyzacji | Pobieranie workflow |
| automation.write | Tworzenie/edycja automatyzacji | Zarządzanie workflow |
| * | Pełny dostęp | Wszystkie uprawnienia (używaj ostrożnie!) |
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
Modal wyświetli:Kliknij Kopiuj i zapisz klucz w bezpiecznym miejscu (np. password manager).
Używanie klucza API
Uwierzytelnianie
Dodaj klucz do nagłówkaAuthorization jako Bearer token:
- cURL
- Node.js (fetch)
- Python (requests)
- PHP
Przykłady użycia
Dodanie nowego kontaktu
Dodanie nowego kontaktu
contacts.writePobieranie statystyk kampanii
Pobieranie statystyk kampanii
campaigns.readBulk import kontaktów
Bulk import kontaktów
contacts.writeWebhook - Abandoned Cart
Webhook - Abandoned Cart
contacts.write, automation.writeZarządzanie kluczami
Przegląd kluczy
W tabeli kluczy API zobaczysz:| Kolumna | Opis |
|---|---|
| Nazwa | Nazwa klucza + liczba uprawnień |
| Klucz API | Zamaskowany klucz (ml_prod_a1b2c3…******) + przycisk kopiuj |
| Status | Aktywny / Odwołany / Wygasły |
| Żądania | Całkowita liczba wywołań API tym kluczem |
| Ostatnie użycie | Data i godzina ostatniego żądania |
| Data utworzenia | Kiedy klucz został wygenerowany |
| Akcje | Menu z opcjami zarządzania |
Filtrowanie kluczy
- Wyszukiwanie
- Filtr statusu
Szukaj po:
- Nazwie klucza
- Fragmencie klucza API
Akcje na kluczach
Dezaktywuj / Aktywuj klucz
Dezaktywuj / Aktywuj klucz
Kiedy używać: Tymczasowe wyłączenie klucza bez usuwaniaJak:
- Menu akcji → Dezaktywuj (lub Aktywuj)
- Status zmienia się na “Odwołany”
- Wszystkie żądania z tym kluczem będą odrzucane (HTTP 401)
- Debugowanie integracji
- Rotacja kluczy (wyłącz stary, włącz nowy)
- Podejrzenie compromisu bezpieczeństwa
Regeneruj klucz
Regeneruj klucz
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)
- Menu akcji → Wygeneruj ponownie
- Potwierdź: “Stary klucz przestanie działać”
- Skopiuj nowy klucz (pokazany raz!)
- Zaktualizuj klucz w swojej aplikacji
Kopiuj klucz
Kopiuj klucz
Kopiuje pełny klucz API do schowka.Uwaga: Klucze są zamaskowane w interfejsie (
ml_prod_a1b2...******), ale przycisk kopiuje pełny klucz.Odwołaj klucz
Odwołaj 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ąć)
Usuń klucz
Usuń klucz
Permanentnie usuwa klucz z systemu.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:- 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 (
.envfile, nie commitowane) - Secrets manager (AWS Secrets, Azure Key Vault)
- Password manager (1Password, LastPass)
- 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)
Rate Limiting
Mailist ma limity żądań API:| Plan | Rate Limit | Burst |
|---|---|---|
| Free | 60 req/min | 10 req/s |
| Starter | 300 req/min | 50 req/s |
| Business | 1,200 req/min | 100 req/s |
| Enterprise | Nieograniczony | Nieograniczony |
Błędy uwierzytelniania
401 Unauthorized
401 Unauthorized
403 Forbidden
403 Forbidden
- Klucz nie ma wymaganego uprawnienia
- Próba dostępu do zasobu poza zakresem uprawnień
- Sprawdź uprawnienia klucza w Integracje → [Twój klucz]
- Edytuj klucz → Dodaj brakujące uprawnienie
- LUB stwórz nowy klucz z odpowiednimi uprawnieniami
429 Too Many Requests
429 Too Many Requests
- 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:- Development
- Staging
- Production
FAQ
Ile kluczy mogę mieć?
Ile kluczy mogę mieć?
Zależy od planu:
- Free: 2 klucze
- Starter: 5 kluczy
- Business: 20 kluczy
- Enterprise: Nieograniczone
- Jeden klucz per aplikacja/środowisko
- Usuń nieużywane klucze
- Grupuj podobne integracje (jeśli bezpieczne)
Co jeśli zgubię klucz API?
Co jeśli zgubię klucz API?
Klucze są pokazane tylko raz przy tworzeniu.Jeśli zgubiłeś:
- Nie możesz go odzyskać - klucze są haszowane w bazie
- Wygeneruj nowy klucz (regeneruj istniejący lub stwórz nowy)
- Zaktualizuj aplikację z nowym kluczem
- Usuń stary klucz
- Zapisuj klucze w password managerze od razu
- Używaj
.envfiles dla lokalnego developmentu - Dokumentuj gdzie każdy klucz jest używany
Czy klucze wygasają automatycznie?
Czy klucze wygasają automatycznie?
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.
Czy mogę używać tego samego klucza na wielu serwerach?
Czy mogę używać tego samego klucza na wielu serwerach?
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)
- Ł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: [email protected]Zgłoś:
- Opis problemu
- Kompromitowany klucz (jeśli dotyczy)
- Timestamp incydentu
