Bezpieczeństwo kluczy API e-mail: uprawnienia, rotacja i przechowywanie

Klucz API e-mail to krótki ciąg znaków o dużej mocy. Kto go ma, może wysyłać pocztę z Twojej domeny, do kogokolwiek, w Twoim imieniu. Wycieki kluczy to jeden z najczęstszych powodów, dla których kampanie phishingowe są wysyłane z infrastruktury legalnych firm.

Dobra wiadomość: kilka nawyków sprawia, że wyciek jest mało prawdopodobny, a jeśli i tak się zdarzy, ogranicza szkody. Ten poradnik je omawia, korzystając z ustawień, które Inbixio oferuje dla każdego klucza.

Co może klucz Inbixio

Każdy klucz utworzony w API Keys → Create Api Key (klucze API → utwórz klucz API) ma trzy ustawienia:

• Name (nazwa), dla Twojej własnej ewidencji, np. prod-auth-service.
• Server Access (dostęp do serwera): All Server (wszystkie serwery; wysyła przez pierwszy podłączony serwer SMTP) lub Selected Server (wybrany serwer; dokładnie ten, który wskażesz).
• Permissions (uprawnienia): Send (wysyłanie), Read (odczyt) i Manage (zarządzanie). API ma obecnie jeden endpoint, do wysyłki e-maili, więc Twoje usługi potrzebują uprawnienia Send.

Klucze mają postać ibx_, po którym następują 32 znaki szesnastkowe. Prefiks ułatwia ich rozpoznanie, a skanerom sekretów ich wychwycenie.

Zasada 1: jeden klucz na usługę i środowisko

Nie używaj jednego klucza w całej firmie. Utwórz osobny klucz dla każdej usługi i każdego środowiska:

Osobne klucze oznaczają, że:

• Wyciek jest ograniczony. Unieważnienie prod-billing nie wyłącza e-maili logowania.
• Każda usługa wysyła z właściwego adresu. Klucz przypięty do serwera billing@ wysyła z billing@, a nie z serwera, który podłączyłeś jako pierwszy. Jeśli usuniesz przypięty serwer, klucz wraca do Twojego pierwszego serwera, więc przy usuwaniu serwerów przypinaj klucze ponownie.
• Rotacja jest bezbolesna. Możesz odnowić klucz jednej usługi, nie ruszając pozostałych.

Zasada 2: najmniejsze wystarczające uprawnienia

Backend wysyłający e-maile potrzebuje Send i niczego więcej, więc zostaw Read i Manage niezaznaczone. Im mniej klucz może, tym mniej kosztuje wyciek.

Zasada 3: klucze na serwerach, nigdy w klientach

Wszystko, co trafia do przeglądarki lub aplikacji mobilnej, da się wydobyć, niezależnie od minifikacji. Dotyczy to:

• paczek JavaScript (React, Vue, komponenty klienckie Next.js),
• zmiennych środowiskowych z prefiksem dla przeglądarki, takich jak NEXT_PUBLIC_, VITE_ lub REACT_APP_,
• plików binarnych aplikacji na iOS i Androida.

Jeśli akcja użytkownika we frontendzie ma wywołać e-mail, wywołaj własny endpoint backendu. Twój backend sprawdza, czy użytkownik może to zrobić, stosuje limity i dopiero wtedy wywołuje Inbixio z kluczem przechowywanym w swoim środowisku.

// ✅ Browser → your API → Inbixio
await fetch('/api/invite', { method: 'POST', body: JSON.stringify({ email }) });

// ❌ Never do this in frontend code
fetch('https://backend.inbixio.com/api/send-email/', {
  headers: { 'X-API-Key': 'ibx_…' }, // visible to every visitor
});

Zasada 4: przechowuj klucze jak hasła

• Trzymaj klucze w menedżerze sekretów (AWS Secrets Manager, Google Secret Manager, Doppler, 1Password, Vault) lub w szyfrowanych zmiennych środowiskowych swojej platformy.
• Nigdy ich nie commituj. Dodaj .env do .gitignore i włącz skanowanie sekretów w repozytoriach; push protection w GitHubie blokuje wiele wycieków, zanim do nich dojdzie.
• Nie zapisuj kluczy w logach. Jeśli logujesz wychodzące żądania, najpierw usuń nagłówek X-API-Key.
• Nie wklejaj kluczy do zgłoszeń, czatu ani zrzutów ekranu. Udostępniaj dostęp do sekretu, a nie jego wartość.

Zasada 5: rotuj regularnie i natychmiast w razie wątpliwości

Inbixio potrafi odnowić klucz: kliknij ikonę odświeżania obok niego na stronie API Keys. Odnowienie wydaje nową wartość z tą samą nazwą, dostępem do serwera i uprawnieniami, a stara wartość natychmiast przestaje działać. Aby zrotować klucz produkcyjny bez ani jednej nieudanej wysyłki:

1. Utwórz drugi klucz z tymi samymi ustawieniami (np. prod-auth-2).
2. Wdróż nowy klucz w usłudze i potwierdź, że jej żądania zwracają 200, np. w logach własnej aplikacji.
3. Usuń stary klucz.

Używaj ikony odświeżania, gdy szybkość jest ważniejsza niż płynne przejście, np. zaraz po wycieku. Rutynowe klucze rotuj co kilka miesięcy oraz zawsze, gdy z zespołu odchodzi ktoś, kto miał do nich dostęp.

Gdy klucz wycieknie

Potraktuj to jak incydent, ale taki, nad którym da się zapanować:

1. Natychmiast odnów (ikona odświeżania) lub usuń klucz. To blokuje każde użycie starej wartości.
2. Sprawdź logi w panelu pod kątem nietypowej aktywności: wywołań o dziwnych porach lub skoku wolumenu. Log pokazuje, kiedy wykonano wywołania, a nie którym kluczem, więc porównaj go z logami własnych usług.
3. Zajrzyj do swojego dostawcy poczty w poszukiwaniu odbić lub zgłoszeń spamu spowodowanych wiadomościami, których nie wysłałeś.
4. Ustal, jak doszło do wycieku, czy przez commit, wpis w logu, czy paczkę frontendu, i zamknij tę drogę.
5. Poinformuj użytkowników, których to dotyczy, jeśli w Twoim imieniu wysłano wiadomości, aby wiedzieli, że mają je zignorować.

Szybka checklista

• Jeden klucz na usługę i środowisko, z czytelnymi nazwami
• Klucze przypięte do serwera (adresu nadawcy), którego ma używać każda usługa
• Tylko uprawnienie Send w usługach wysyłających
• Brak kluczy w kodzie frontendu, aplikacjach mobilnych i repozytoriach
• Klucze przechowywane w menedżerze sekretów i usuwane z logów
• Termin rotacji w kalendarzu i plan na wypadek wycieku

Bezpieczeństwo chroni Cię też przed folderem spamu: wiadomości wysłane przejętym kluczem szkodzą reputacji Twojej domeny. Połącz tę checklistę z SPF, DKIM i DMARC, aby mieć pełny obraz.