Tworzenie i zarządzanie kluczem API

Published: 16 lipca 2026 · Last updated: 21 lipca 2026 · By Marcus Biel

Strona klucza API zapewnia zewnętrznemu systemowi uwierzytelniony dostęp do obsługiwanych endpointów API Maildroppa na Twoim koncie.

Możesz utworzyć jeden klucz API, skopiować jego pełną wartość tajną, bezpiecznie go zresetować poprzez rotację lub usunąć, gdy nie jest już potrzebny. Ten sam klucz konta może być używany przez integracje po stronie serwera oraz przez wyzwalacze żądań API w Maildroppa Automations.

Klucz API reprezentuje Twoje konto Maildroppa. Traktuj go jak hasło: każda osoba, która zdobędzie klucz, może wywoływać dostępne dla niego endpointy API do momentu jego rotacji lub usunięcia.

Do czego służy klucz API

Używaj klucza API, gdy oprogramowanie spoza Maildroppa musi współpracować z Maildroppa bez interaktywnego logowania użytkownika.

Typowe przykłady:

• Synchronizowanie subskrybentów z systemem CRM, sklepem, systemem członkowskim lub wewnętrzną bazą danych.
• Tworzenie lub aktualizowanie subskrybentów z aplikacji działającej po stronie serwera.
• Odczytywanie tagów, pól, wartości pól i segmentów oraz zarządzanie nimi za pomocą obsługiwanych endpointów.
• Wysyłanie niestandardowych zdarzeń do wyzwalacza żądania API w Automation.
• Wysyłanie transakcyjnych wiadomości e-mail za pośrednictwem API.
• Zarządzanie subskrypcjami webhooków opartymi na API.

Klucz API jest przeznaczony do komunikacji serwer-serwer. Nie jest przeznaczony do kodu uruchamianego w przeglądarce odwiedzającego, publicznej witrynie, aplikacji mobilnej ani osadzonym formularzu zapisu.

Strona jest obecnie oznaczona jako „beta”. Połączona dokumentacja OpenAPI jest źródłem informacji o endpointach, treściach żądań, parametrach i schematach odpowiedzi obecnie obsługiwanych przez API.

Otwieranie strony klucza API

Otwórz „Settings”, rozwiń „Developers” i wybierz „API key”.

Możesz również otworzyć stronę bezpośrednio pod adresem:

https://app.maildroppa.com/settings/developers/api-key

Strona zawiera:

• Panel klucza API z oznaczeniem beta.
• Link „View OpenAPI docs”.
• Pusty stan i przycisk „Create API key”, gdy nie istnieje żaden klucz.
• Zamaskowaną reprezentację bieżącego klucza, gdy taki klucz istnieje.
• Przycisk „Copy”, który kopiuje kompletny klucz.
• Działania „Rotate API key” i „Delete API key” służące do zastąpienia lub usunięcia bieżącego klucza.

Maildroppa umożliwia utworzenie jednego klucza API na konto. Strona nie tworzy osobnych kluczy dla poszczególnych aplikacji, środowisk ani członków zespołu.

Tworzenie klucza API

Gdy na stronie wyświetla się komunikat „No API key yet”, kliknij „Create API key”.

Maildroppa tworzy klucz natychmiast. Przy pierwszym tworzeniu nie ma okna dialogowego z potwierdzeniem. Podczas wykonywania żądania przycisk zmienia się na „Creating API key”, a strona tymczasowo wyłącza dalsze działania związane z kluczem.

Po utworzeniu klucza:

• Pusty stan znika.
• Pojawia się zamaskowany klucz.
• Dostępne stają się działania „Copy”, „Rotate API key” i „Delete API key”.
• Maildroppa wyświetla komunikat o pomyślnym zakończeniu „API key updated”.

Jeśli na koncie istnieje już inny klucz, Maildroppa nie utworzy drugiego. Użyj istniejącego klucza lub poddaj go rotacji.

Zrozumienie zamaskowanego klucza

Strona nie wyświetla pełnej wartości tajnej jako zwykłego tekstu. Pokazuje pierwsze pięć znaków, a następnie pięć gwiazdek, na przykład:

a1b2c*****

To tylko maska wizualna. Gwiazdki nie oznaczają rzeczywistej długości klucza, a zamaskowanej wartości nie można użyć w żądaniu API.

Kliknij „Copy”, aby zapisać pełny bieżący klucz w schowku. Po pomyślnym skopiowaniu przycisk na krótko zmienia się na „Copied!”.

Po powrocie na stronę klucz pozostaje zamaskowany, ale przycisk „Copy” nadal kopiuje jego pełną bieżącą wartość. Nie musisz więc poddawać prawidłowego klucza rotacji tylko dlatego, że nie zapisano go podczas tworzenia.

Bezpieczne przechowywanie klucza

Przenieś skopiowany klucz bezpośrednio do magazynu sekretów używanego przez integrację.

Odpowiednie miejsca obejmują:

• Zarządzany menedżer sekretów.
• Chronioną konfigurację środowiska serwera.
• Zaszyfrowany sekret wdrożeniowy.
• Menedżer haseł używany do odzyskiwania dostępu operacyjnego.

Nie przechowuj klucza w:

• JavaScript po stronie przeglądarki ani innym możliwym do pobrania pakiecie frontendowym.
• Publicznym ani prywatnym pliku kodu źródłowego zatwierdzonym w repozytorium.
• Adresie URL ani parametrze zapytania.
• Publicznej dokumentacji, zrzutach ekranu, wiadomościach do pomocy technicznej ani systemach śledzenia zgłoszeń.
• Wspólnych logach aplikacji, zdarzeniach analitycznych ani raportach błędów.
• Niezaszyfrowanym arkuszu kalkulacyjnym ani zwykłym czacie zespołowym.

Nie dodawaj klucza do przykładu curl, który zostanie skopiowany do dokumentacji lub współdzielonej historii powłoki. Zamiast tego użyj zmiennej środowiskowej, takiej jak MAILDROPPA_API_KEY.

Używanie klucza API

Wysyłaj pełny klucz w nagłówku żądania HTTP X-API-Key:

X-API-Key: your-complete-api-key

Nie wysyłaj go jako tokenu Bearer. Maildroppa oczekuje X-API-Key, a nie Authorization: Bearer ....

Produkcyjne API i jego interaktywna dokumentacja OpenAPI są dostępne pod adresem:

https://api.maildroppa.com

Kliknij „View OpenAPI docs” na stronie klucza API, aby otworzyć dokumentację w nowej karcie przeglądarki. Wybierz tam endpoint, aby sprawdzić jego metodę, ścieżkę, parametry, treść żądania, typ odpowiedzi i możliwe kody statusu.

Przykładowe żądanie

Poniższy przykład pobiera pierwszą stronę subskrybentów. Odczytuje klucz ze zmiennej środowiskowej zamiast umieszczać sekret bezpośrednio w poleceniu:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

Ustaw zmienną w bezpiecznym środowisku, w którym działa integracja. Dokładna metoda, ścieżka, parametry zapytania i treść zależą od endpointu. Skopiuj te informacje z dokumentacji OpenAPI, zamiast zgadywać je na podstawie działań dostępnych w aplikacji Maildroppa.

Żądania z treścią JSON

W przypadku żądania wysyłającego JSON dodaj również:

Content-Type: application/json

Podstawowa struktura wygląda na przykład tak:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint i jego treść to symbole zastępcze. Zastąp je udokumentowanym endpointem i jego udokumentowanym schematem żądania.

Do czego klucz zapewnia dostęp

Klucz działa wyłącznie z endpointami obsługującymi uwierzytelnianie za pomocą klucza API. Strona lub żądanie używane wewnętrznie przez aplikację Maildroppa nie jest automatycznie częścią publicznego API klienta.

Dokumentacja OpenAPI przedstawia obsługiwane API klienta. Jeśli ścieżka nie jest udokumentowana jako przeznaczona do użycia z kluczem API, nie zakładaj, że klucz zapewnia do niej dostęp.

Strona klucza API nie oferuje zakresów uprawnień ani pól wyboru uprawnień dla poszczególnych endpointów. Z tego względu bieżący klucz konta należy traktować jako cenne poświadczenie, nawet jeśli jedna integracja korzysta tylko z jednego endpointu.

Limity szybkości

Obecny kontrakt OpenAPI dokumentuje następujące limity dla kluczy API:

• Domyślne API klienta: 300 żądań na minutę i 2000 żądań na godzinę.
• Events API pod adresem /events: 100 żądań na sekundę, z możliwością obsługi serii do 500 żądań.

Limity te są stosowane do konta Maildroppa, a nie niezależnie do każdego skryptu współdzielącego jego klucz. Kilka integracji może więc wykorzystać ten sam przydział.

Gdy Maildroppa zwróci 429 Too Many Requests, przestań wysyłać nowe żądania i przestrzegaj nagłówka odpowiedzi Retry-After, jeśli jest obecny. Używaj kolejki i kontrolowanego wycofywania zamiast uruchamiać wiele równoległych ponowień.

Zasady limitów mogą ewoluować, gdy API jest w wersji beta. Przed zaprojektowaniem integracji o dużym wolumenie sprawdź informacje na początku dokumentacji OpenAPI.

Używanie klucza do żądań API Automation

Automation może rozpocząć działanie, gdy Twój system wyśle niestandardowe zdarzenie do Events API Maildroppa.

Po skonfigurowaniu wyzwalacza „API request” Maildroppa używa tego samego klucza API konta zarządzanego na tej stronie. Konfiguracja wyzwalacza może utworzyć klucz, jeśli żaden nie istnieje, oraz skopiować przygotowane żądanie curl zawierające pełny klucz.

Ma to dwie ważne konsekwencje:

• Rotacja lub usunięcie klucza konta wpływa również na systemy wysyłające niestandardowe zdarzenia do Automations.
• Skopiowany przykład żądania Automation zawiera sekret w schowku, mimo że klucz jest zamaskowany na ekranie.

Przed rotacją lub usunięciem klucza uwzględnij w wykazie integracji każdy wyzwalacz żądania API i każdego zewnętrznego nadawcę zdarzeń.

Resetowanie lub zastępowanie klucza API

Użyj opcji „Rotate API key”, gdy musisz zresetować lub zastąpić bieżące poświadczenie. Maildroppa tworzy nowy klucz i unieważnia poprzedni w ramach tego samego działania.

Użyj rotacji, gdy:

• Klucz mógł zostać ujawniony.
• Osoba lub dostawca znający klucz nie potrzebuje już dostępu.
• Twoja polityka bezpieczeństwa wymaga okresowej wymiany poświadczeń.
• Chcesz zastąpić klucz przechowywany w starym lub niezabezpieczonym miejscu.

Kliknij „Rotate API key” pod zamaskowanym kluczem. Maildroppa otworzy okno ostrzegawcze wyjaśniające, że istniejącego klucza nie będzie można już używać.

Kliknij „Rotate API key” w oknie dialogowym, aby kontynuować, lub kliknij „Cancel”, aby zachować bieżący klucz.

Rotacja nie ma okresu karencji

Po potwierdzeniu rotacji stary klucz przestaje działać natychmiast. Maildroppa nie utrzymuje jednocześnie ważności starego i nowego klucza.

Ponieważ konto ma tylko jeden klucz, rotacja wpływa na każdy serwer, zadanie zaplanowane, integrację, skrypt i nadawcę zdarzeń Automation, który go używa.

W przypadku planowanej rotacji zastosuj następującą kolejność:

1. Wymień każdą integrację korzystającą z bieżącego klucza.
2. Przygotuj dostęp do konfiguracji sekretów i procesu wdrażania każdej integracji.
3. Jeśli nieprzerwany dostęp do API jest ważny, wybierz krótkie okno serwisowe.
4. Kliknij „Rotate API key”, a następnie potwierdź ostrzeżenie, klikając „Rotate API key” w oknie dialogowym.
5. Kliknij „Copy”, aby skopiować pełny nowy klucz.
6. Natychmiast zastąp sekret w każdej integracji.
7. Uruchom ponownie lub wdróż ponownie usługi, które wczytują sekrety tylko podczas uruchamiania.
8. Wyślij nieszkodliwe, udokumentowane żądanie, aby zweryfikować każdą integrację.
9. Sprawdź, czy zapomniana usługa nadal używająca starego klucza zwraca odpowiedzi 401 Unauthorized.

Jeśli podejrzewasz, że bieżący klucz został przejęty, natychmiast przeprowadź jego rotację i zaakceptuj krótką przerwę potrzebną na aktualizację prawidłowych systemów.

Usuwanie klucza API

Usuń klucz, gdy konto nie powinno już akceptować żądań uwierzytelnianych za pomocą klucza API.

Kliknij „Delete API key” pod zamaskowanym kluczem. Maildroppa otworzy okno ostrzegawcze wyjaśniające, że klucz zostanie trwale usunięty z konta.

Kliknij „Delete API key” w oknie dialogowym, aby go usunąć, lub kliknij „Cancel”, aby go zachować.

Po usunięciu:

• Bieżący klucz natychmiast przestaje działać.
• Strona wraca do stanu „No API key yet”.
• Integracje serwerowe korzystające z usuniętego klucza nie mogą już się uwierzytelnić.
• Nadawcy żądań API Automation korzystający z tego klucza nie mogą już dostarczać zdarzeń.

Usunięcie klucza nie usuwa subskrybentów, kampanii, tagów, pól, segmentów, Automations ani innych danych konta. Usuwa poświadczenie używane do uzyskiwania dostępu do obsługiwanych endpointów API.

Później możesz kliknąć „Create API key”, aby utworzyć nowe poświadczenie. Usunięta wartość nie zostanie przywrócona. Każdą integrację trzeba zaktualizować, zanim będzie mogła używać nowego klucza.

Resetowanie czy usuwanie: co wybrać?

Wybierz „Rotate API key”, gdy dostęp do API ma być kontynuowany z użyciem nowych poświadczeń.

Wybierz usunięcie, gdy dostęp do API ma zostać całkowicie zatrzymany, przynajmniej na razie.

Oba działania natychmiast unieważniają bieżący klucz. Rotacja tworzy zastępstwo w ramach tego samego działania, natomiast usunięcie pozostawia konto bez klucza.

Zalecenia dotyczące bezpieczeństwa

Wykonuj wywołania API na swoim serwerze

Przeglądarka ani aplikacja mobilna nie mogą niezawodnie chronić osadzonego sekretu. Użytkownik może przeanalizować aplikację, nagłówki żądań, mapy źródeł lub ruch sieciowy i wyodrębnić klucz.

Jeśli witryna lub aplikacja musi wywołać działanie, najpierw wyślij żądanie do własnego uwierzytelnionego backendu. Niech backend zweryfikuje użytkownika i wywoła Maildroppa, korzystając z klucza przechowywanego na serwerze.

Ogranicz ekspozycję do minimum

Udostępniaj klucz tylko systemom, które go potrzebują. Nie przekazuj go każdemu programiście ani nie wklejaj do wielu lokalnych plików konfiguracyjnych.

Ponieważ strona obecnie zarządza jednym kluczem dla całego konta, a nie wieloma nazwanymi kluczami lub kluczami o określonych zakresach, użyj wewnętrznej usługi integracyjnej lub serwera proxy, jeśli kilka aplikacji potrzebuje silniejszej izolacji.

Redaguj nagłówki żądań

Skonfiguruj klientów HTTP, odwrotne serwery proxy, narzędzia obserwowalności i raportery błędów tak, aby redagowały X-API-Key. Żądanie może działać prawidłowo, a jednocześnie ujawniać poświadczenie w logach debugowania.

Utrzymuj oddzielne środowiska

Nie używaj ponownie klucza produkcyjnego w lokalnym środowisku programistycznym, przykładowym kodzie, zrzutach ekranu ani danych testowych. Przechowuj sekrety środowiskowe w magazynach sekretów przeznaczonych dla konkretnych środowisk.

Link „View OpenAPI docs” automatycznie kieruje użytkowników produkcyjnych do dokumentacji produkcyjnego API. Zawsze sprawdzaj nazwę hosta przed wysłaniem prawdziwego klucza.

Wykonaj rotację po każdym podejrzeniu ujawnienia

Usunięcie wiadomości, zatwierdzenia w repozytorium, wiersza logu lub zrzutu ekranu nie dowodzi, że nikt nie skopiował klucza. Jeśli pełna wartość została ujawniona, przeprowadź jej rotację.

Obsługa błędów API

Na podstawie statusu HTTP i udokumentowanej treści odpowiedzi zdecyduj, co powinna zrobić integracja.

Typowe przypadki obejmują:

• 400 Bad Request — Ścieżka, parametr lub treść JSON nie spełnia wymagań kontraktu endpointu. Porównaj żądanie ze schematem OpenAPI.
• 401 Unauthorized — Brakuje nagłówka X-API-Key, jest on pusty lub nieprawidłowy, klucz został usunięty albo po rotacji używana jest stara wartość.
• 403 Forbidden — Uwierzytelniony klucz nie ma uprawnień do wykonania tej operacji.
• 404 Not Found — Ścieżka lub wskazany zasób nie istnieje na tym koncie.
• 429 Too Many Requests — Integracja osiągnęła limit szybkości API. Wstrzymaj żądania i przestrzegaj nagłówka Retry-After, jeśli jest obecny.
• 5xx — Maildroppa nie mogła ukończyć żądania. Ponawiaj bezpieczne operacje z ograniczonym wykładniczym wycofywaniem i logowaniem, które nie zawiera klucza API.

Nie ponawiaj bezmyślnie każdej nieudanej operacji. Popraw odpowiedzi 400, 401, 403 i większość odpowiedzi 404, zanim ponownie wyślesz to samo żądanie.

W przypadku żądań modyfikujących sprawdź zachowanie endpointu dotyczące ponawiania i idempotencji, zanim automatycznie powtórzysz żądanie. Błąd połączenia nie zawsze oznacza, że Maildroppa nie wprowadziła żadnej zmiany.

Rozwiązywanie problemów

Nadal widoczny jest przycisk „Create API key”

Na koncie obecnie nie istnieje żaden klucz. Kliknij przycisk raz i poczekaj na zakończenie żądania.

Jeśli tworzenie się nie powiedzie, odśwież stronę przed ponowną próbą. Inna strona lub konfiguracja Automation mogła już utworzyć klucz konta.

Klucz na stronie wygląda na zbyt krótki

Strona celowo pokazuje tylko pierwszych pięć znaków i *****. Kliknij „Copy”, aby skopiować pełną wartość. Nie wysyłaj zamaskowanego tekstu w żądaniu.

Przycisk „Copy” nie zmienia się na „Copied!”

Przeglądarka mogła zablokować dostęp do schowka. Pozostaw stronę w aktywnej karcie, zezwól na dostęp do schowka, jeśli pojawi się monit, i ponownie kliknij „Copy”.

Nie próbuj odtworzyć klucza na podstawie zamaskowanego tekstu.

Żądanie zwraca 401 Unauthorized

Sprawdź, czy:

• Nazwa nagłówka to dokładnie X-API-Key.
• Nagłówek zawiera pełną wartość bez widocznych gwiazdek.
• Integracja nie wysyła zamiast tego Authorization: Bearer.
• Do sekretu nie dodano białych znaków, cudzysłowów ani znaku nowej linii.
• Nikt nie poddał klucza konta rotacji ani go nie usunął.
• Usługa została ponownie uruchomiona, jeśli odczytuje zmienne środowiskowe tylko podczas uruchamiania.
• Żądanie jest wysyłane do prawidłowego środowiska API Maildroppa.

Jedna integracja działa, ale druga przestała działać po rotacji

Druga integracja prawdopodobnie nadal używa starego klucza. Nie ma okresu, w którym oba klucze są ważne. Zaktualizuj jej sekret i uruchom ponownie proces, który buforuje konfigurację.

Strona OpenAPI działa, ale endpoint zwraca 403

Nie każdy endpoint aplikacji obsługuje uwierzytelnianie za pomocą klucza API. Użyj operacji udokumentowanej dla API klienta i potwierdź wymagania dotyczące uwierzytelniania na stronie OpenAPI.

Żądania zwracają 429 Too Many Requests

Ogranicz serie żądań, umieść pracę w kolejce i ponawiaj po czasie zwróconym przez API. Unikaj równoległych lawin ponowień. Jeśli kilka aplikacji współdzieli jeden klucz konta, skoordynuj ich liczbę żądań, ponieważ współdzielą limity API konta.

Zalecana lista kontrolna konfiguracji

Przed rozpoczęciem regularnego korzystania z integracji potwierdź, że:

• Klucz jest przechowywany wyłącznie w konfiguracji sekretów po stronie serwera.
• Żądania używają nagłówka X-API-Key.
• Integracja korzysta w środowisku produkcyjnym z https://api.maildroppa.com.
• Każda metoda, ścieżka, parametr i treść JSON są zgodne z dokumentacją OpenAPI.
• Logi i raporty błędów redagują klucz.
• Skonfigurowano limity czasu i ograniczone ponowienia.
• Monitorowane są błędy 401, 403, 429 i błędy serwera.
• Zapisano właściciela integracji.
• Każdy system współdzielący klucz konta uwzględniono w planie rotacji.
• Przejęty klucz można szybko poddać rotacji.

Strona klucza API jest celowo niewielka, ale jej działania wpływają na każdą integrację API połączoną z kontem. Twórz klucz tylko wtedy, gdy jest potrzebny, przechowuj go na zaufanych serwerach i planuj rotację jako zmianę poświadczenia obejmującą całe konto.