Jak działają klucze API?

Klucze API są Twoimi danymi uwierzytelniającymi do korzystania z API Cathopic. Zrozumienie, jak działają, jest niezbędne dla bezpiecznej i skutecznej integracji z API.

Czym jest klucz API?

Klucz API to unikalny tajny token, który identyfikuje Twoją aplikację i upoważnia ją do dostępu do API Cathopic:

• Długi ciąg znaków alfanumerycznych (np. sk_live_abc123xyz789...)

• Działa zarówno jako uwierzytelnianie, jak i autoryzacja

• Jest powiązany z Twoim kontem Cathopic i rozliczeniami

• Może być aktywny lub nieaktywny

Cykl życia klucza

Tworzenie:

1. Wygeneruj klucze w Ustawienia → API

2. Nadaj każdemu kluczowi opisową nazwę ("Production Website", "Staging", "Mobile App")

3. Skopiuj pełny klucz od razu — jest wyświetlany tylko raz

4. Przechowuj bezpiecznie (zmienne środowiskowe, menedżer sekretów, menedżer haseł)

Użycie:

• Dołącz do nagłówka HTTP x-api-key w przypadku każdej prośby

• Klucze są weryfikowane po stronie serwera w każdej prośbie

• Wszystkie użycia API są rejestrowane i rozliczane na Twoim koncie

Dezaktywacja:

• Klucze można tymczasowo wyłączyć bez usuwania

• Przydatne do diagnozowania problemów lub wstrzymania konkretnej integracji

• Można je ponownie aktywować w dowolnym momencie

Usunięcie:

• Trwale usuwa klucz

• Nie można tego cofnąć ani odzyskać

• Wszystkie prośby z tym kluczem zakończą się natychmiast niepowodzeniem

Zasady zarządzania kluczami

Bezpieczeństwo:

• Nigdy nie zapisuj kluczy w systemie kontroli wersji: Użyj plików .env i dodaj je do .gitignore

• Nigdy nie ujawniaj w kodzie po stronie klienta: Klucze API powinny być używane wyłącznie po stronie serwera

• Używaj zmiennych środowiskowych: Przechowuj klucze w process.env.CATHOPIC_API_KEY lub odpowiedniku

• Regularnie rotuj: Zmieniaj klucze okresowo (co kwartał lub po zmianach w zespole)

• Używaj osobnych kluczy dla każdego środowiska: Różne klucze dla dev, staging i produkcji

Organizacja:

• Opisowe nazwy: Nazywaj klucze według przeznaczenia: "Production Website", "iOS App", "Email System"

• Dokumentuj właściciela: Śledź, który członek zespołu utworzył każdy klucz

• Regularne audyty: Przeglądaj aktywne klucze co miesiąc i usuwaj te nieużywane

Wiele kluczy API

Możesz utworzyć wiele kluczy API do różnych celów:

• Na środowisko: Oddzielne klucze dla development, staging, produkcji

• Na aplikację: Różne klucze dla strony internetowej, aplikacji mobilnej, narzędzi wewnętrznych

• Na członka zespołu: Indywidualne klucze dla programistów (łatwiejsze do śledzenia i cofnięcia)

Wszystkie klucze w ramach Twojego konta współdzielą to samo rozliczenie. Użycie ze wszystkich kluczy jest sumowane w Twojej miesięcznej fakturze.

Monitorowanie użycia klucza

Śledź aktywność dla każdego klucza:

1. Przejdź do Ustawienia → API

2. Zobacz listę wszystkich kluczy wraz z datami ostatniego użycia

3. Kliknij klucz, aby zobaczyć szczegółowe statystyki użycia

4. Monitoruj pod kątem nieoczekiwanej aktywności

Co zrobić, jeśli klucz został naruszony

Jeśli uważasz, że klucz API został ujawniony:

1. Natychmiast usuń lub dezaktywuj klucz w Ustawienia → API

2. Wygeneruj nowy klucz zastępczy

3. Zaktualizuj swoją aplikację o nowy klucz

4. Przejrzyj logi użycia pod kątem podejrzanej aktywności

5. Skontaktuj się z pomocą, jeśli widzisz nieautoryzowane użycie

Przykład: bezpieczne przechowywanie kluczy

Node.js ze zmiennymi środowiskowymi:

// plik .env (dodaj do .gitignore!)
CATHOPIC_API_KEY=sk_live_abc123xyz789...
// Twój kod
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'Jesus' })
});

Python ze zmiennymi środowiskowymi:

import os
import requests
api_key = os.environ.get('CATHOPIC_API_KEY')
response = requests.post(
    'https://api.cathopic.com/resources',
    headers={'x-api-key': api_key},
    json={'query': 'Jesus'}
)