Dokumentacja / Szybki start

Autentykacja

2 min czytania

Wszystkie żądania API wymagają uwierzytelnienia kluczem API. Ta strona wyjaśnia jak tworzyć, używać i zarządzać kluczami API.

Format klucza API

Klucze API Outboxa wyglądają tak:

ob_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
ob_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Prefiks wskazuje środowisko:

  • ob_live_ — Klucze produkcyjne, emaile są wysyłane naprawdę
  • ob_test_ — Klucze sandbox, emaile są symulowane (wkrótce)

Używanie klucza API

Dołącz klucz API w nagłówku Authorization ze schematem Bearer:

curl -X POST https://api.mailingapi.com/v1/messages/send \
  -H "Authorization: Bearer ob_live_twój_klucz" \
  -H "Content-Type: application/json" \
  -d '{"from": "...", "to": "...", "subject": "...", "html": "..."}'

Python

import requests

headers = {
    "Authorization": "Bearer ob_live_twój_klucz",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.mailingapi.com/v1/messages/send",
    headers=headers,
    json={...}
)

JavaScript

const response = await fetch('https://api.mailingapi.com/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ob_live_twój_klucz',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({...})
});

Uprawnienia kluczy API

Każdy klucz API ma poziom uprawnień kontrolujący dostępne operacje:

Uprawnienie Może wykonać
send Wysyłać emaile, analizować treść
read Odczytywać wiadomości, zdarzenia, statystyki
manage Zarządzać domenami, szablonami, webhookami, kluczami API
admin Pełny dostęp włącznie z billingiem

Tworząc klucz API, wybierz minimalne wymagane uprawnienia. Jeśli Twój backend tylko wysyła emaile, użyj klucza z uprawnieniem send.

Powiązanie z domeną

Każdy klucz API jest powiązany z konkretną domeną. Adres from w emailach musi odpowiadać domenie klucza:

Domena klucza: notifications.example.com
✓ from: "alerts@notifications.example.com"
✓ from: "no-reply@notifications.example.com"
✗ from: "hello@inna-domena.com" — błąd

To zapobiega nieautoryzowanej wysyłce z domen, których nie kontrolujesz.

Tworzenie kluczy API

Przez Dashboard

  1. Przejdź do Ustawienia → Klucze API
  2. Kliknij Utwórz nowy klucz
  3. Wybierz domenę i uprawnienia
  4. Skopiuj i bezpiecznie przechowaj klucz

Pełny klucz jest pokazywany tylko raz. Przechowuj go w menedżerze sekretów lub zmiennych środowiskowych.

Przez API

curl -X POST https://api.mailingapi.com/v1/api-keys \
  -H "Authorization: Bearer ob_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Production",
    "domain_id": "dom_123abc",
    "permissions": ["send", "read"]
  }'

Rotacja kluczy

Aby rotować klucz bez przestoju:

  1. Utwórz nowy klucz z tymi samymi uprawnieniami
  2. Zaktualizuj aplikację, by używała nowego klucza
  3. Usuń lub unieważnij stary klucz

Lub użyj wbudowanej rotacji z okresem karencji:

curl -X POST https://api.mailingapi.com/v1/api-keys/key_123/rotate \
  -H "Authorization: Bearer ob_live_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"grace_period_minutes": 60}'

Oba klucze działają w okresie karencji, dając czas na wdrożenie aktualizacji.

Dobre praktyki bezpieczeństwa

Rób

  • Przechowuj klucze w zmiennych środowiskowych lub menedżerze sekretów
  • Używaj osobnych kluczy dla różnych środowisk (staging, produkcja)
  • Używaj minimalnych wymaganych uprawnień
  • Rotuj klucze regularnie (zalecane co 90 dni)
  • Monitoruj użycie kluczy w dashboardzie

Nie rób

  • Nie commituj kluczy do kontroli wersji
  • Nie dziel kluczy między aplikacjami
  • Nie używaj kluczy admin gdy wystarczy send
  • Nie loguj kluczy API w aplikacji

Obsługa błędów autentykacji

Jeśli autentykacja się nie powiedzie, otrzymasz odpowiedź 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Częste przyczyny:

  • Brak nagłówka Authorization
  • Nieprawidłowy format klucza (nie zaczyna się od ob_)
  • Unieważniony lub usunięty klucz
  • Klucz nie ma wymaganych uprawnień
  • Adres from nie pasuje do domeny klucza

Rate limiting

Żądania API są limitowane per klucz. Gdy przekroczysz limit, otrzymasz 429 Too Many Requests:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "retry_after": 60
  }
}

Poczekaj retry_after sekund przed ponowną próbą. Implementuj exponential backoff w aplikacjach produkcyjnych.

Limity zależą od planu:

Plan Żądań/minutę
Free 60
Starter 300
Pro 1000
Enterprise Custom

Następne kroki

Teraz, gdy rozumiesz autentykację, naucz się obsługiwać błędy.

Obsługa błędów →