Klucze API

Klucze API użytkownika zapewniają bezpieczne uwierzytelnianie dla skryptów, integracji i automatycznych przepływów pracy we wszystkich Twoich tematach.

Porównanie metod uwierzytelniania

Szczegółowe porównanie kluczy API z tokenami dostępu do tematów znajdziesz w Uwierzytelnianie.

Przegląd

Dlaczego warto używać kluczy API?

• Uwierzytelnianie skryptów i automatyzacji
• Unikanie ujawniania danych uwierzytelniających użytkownika
• Śledzenie użycia API na klucz
• Zakres uprawnień (publikowanie, subskrypcja, zarządzanie)
• Ustawianie dat wygaśnięcia

Tworzenie kluczy API

Przez panel webowy

1. Przejdź do Ustawienia → Klucze API
2. Kliknij "Utwórz klucz API"
3. Wprowadź nazwę i opis
4. Wybierz zakresy (uprawnienia)
5. Opcjonalnie ustaw datę wygaśnięcia
6. Skopiuj wygenerowany klucz (wyświetlany tylko raz!)

Przez API

curl -X POST https://app.notifer.io/api/keys \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-script-key",
    "description": "Automation script",
    "scopes": ["publish", "subscribe"]
  }'

Odpowiedź:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "my-script-key",
  "key": "noti_1234567890abcdefghijklmnopqrstuv",
  "key_prefix": "noti_123",
  "description": "Automation script",
  "scopes": ["publish", "subscribe"],
  "request_count": 0,
  "is_active": true,
  "created_at": "2025-11-02T10:00:00Z",
  "last_used": null,
  "expires_at": null,
  "is_valid": true
}

Zapisz swój klucz

Klucz API jest wyświetlany tylko raz podczas tworzenia. Zapisz go bezpiecznie! Jeśli go zgubisz, będziesz musiał utworzyć nowy klucz.

Używanie kluczy API

Użyj nagłówka X-API-Key w żądaniach HTTP:

curl -d "Automated message" \
  -H "X-API-Key: noti_your_key_here" \
  https://app.notifer.io/my-topic

Przykłady kodu

Przykłady użycia kluczy API w Python, JavaScript, CLI i innych językach znajdziesz w Uwierzytelnianie - przykłady kodu.

Zakresy kluczy

Kontroluj, co każdy klucz API może robić:

Zakres	Opis	Przykładowy przypadek użycia
* (wszystkie)	Pełny dostęp	Rozwój i testowanie
publish	Publikowanie wiadomości do tematów	Powiadomienia CI/CD
subscribe	Subskrybowanie tematów	Agregacja logów
topics:read	Wyświetlanie i przeglądanie tematów	Panel monitorowania
topics:write	Tworzenie i zarządzanie tematami	Skrypty automatyzacji
account:read	Odczyt informacji o koncie	Przeglądarki profilu
account:write	Aktualizacja ustawień konta	Automatyzacja ustawień
keys:read	Przeglądanie kluczy API	Skrypty audytowe
keys:write	Zarządzanie kluczami API	Automatyzacja administracyjna

Najlepsze praktyki dotyczące zakresów

=== "Pipeline CI/CD"

```bash
# Wymaga tylko uprawnienia do publikowania
curl -X POST https://app.notifer.io/api/keys \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "scopes": ["publish"]}'
```

=== "Skrypt monitorujący"

```bash
# Wymaga uprawnień do odczytu i publikowania
curl -X POST https://app.notifer.io/api/keys \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "monitoring", "scopes": ["publish", "topics:read"]}'
```

=== "Automatyzacja administracyjna"

```bash
# Pełny dostęp (domyślnie gdy zakresy pominięte)
curl -X POST https://app.notifer.io/api/keys \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "admin-script"}'
```

Zarządzanie kluczami

Wyświetl wszystkie klucze

curl https://app.notifer.io/api/keys \
  -H "Authorization: Bearer your_jwt_token"

Unieważnij klucz

Tymczasowo wyłącz klucz (można ponownie włączyć):

curl -X POST https://app.notifer.io/api/keys/{key_id}/revoke \
  -H "Authorization: Bearer your_jwt_token"

Usuń klucz

Trwale usuń klucz (nieodwracalne):

curl -X DELETE https://app.notifer.io/api/keys/{key_id} \
  -H "Authorization: Bearer your_jwt_token"

Wygaśnięcie klucza

Ustaw daty wygaśnięcia dla tymczasowego dostępu przy tworzeniu kluczy przez API:

curl -X POST https://app.notifer.io/api/keys \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "temp-key",
    "expires_at": "2025-12-02T00:00:00Z"
  }'

Wygasłe klucze:

• Automatycznie przestają działać w momencie wygaśnięcia
• Można je zobaczyć w panelu (oznaczone jako "wygasłe")
• Nie można ich ponownie włączyć (zamiast tego utwórz nowy klucz)

Śledzenie użycia

Monitoruj użycie klucza API w panelu:

• Liczba żądań - Całkowita liczba żądań wykonanych z tym kluczem
• Ostatnie użycie - Znacznik czasu ostatniego użycia
• Użycie według endpointu - Podział wywołań API
• Status limitu szybkości - Bieżące użycie limitu szybkości

Najlepsze praktyki bezpieczeństwa

Przechowywanie

Rób:

• Przechowuj klucze w zmiennych środowiskowych
• Używaj menedżerów sekretów (AWS Secrets Manager, HashiCorp Vault)
• Używaj przechowywania sekretów CI/CD (GitHub Secrets, GitLab CI Variables)
• Regularnie rotuj klucze

Nie rób:

• Nie commituj kluczy do kontroli wersji
• Nie udostępniaj kluczy w postaci zwykłego tekstu (e-mail, czat)
• Nie używaj tego samego klucza w wielu usługach
• Nie przyznawaj więcej uprawnień niż potrzeba

Zmienne środowiskowe

# Przechowuj w pliku .env (nie commituj!)
NOTIFER_API_KEY=noti_your_key_here

# Załaduj w skrypcie
source .env
curl -H "X-API-Key: $NOTIFER_API_KEY" \
  https://app.notifer.io/my-topic

GitHub Actions Secrets

- name: Publish notification
  run: |
    curl -d "Deploy completed" \
      -H "X-API-Key: ${{ secrets.NOTIFER_API_KEY }}" \
      https://app.notifer.io/deployments

Docker Secrets

# Utwórz sekret
echo "noti_your_key_here" | docker secret create notifer_key -

# Użyj w serwisie
docker service create \
  --name app \
  --secret notifer_key \
  myapp

Limity szybkości

Klucze API dziedziczą limity szybkości z planu Twojego konta:

Plan	Limit szybkości	Burst
FREE	10/min	100/h
ESSENTIALS	30/min	300/h
TEAM	100/min	1000/h

Nagłówki limitu szybkości w odpowiedzi:

curl -i -H "X-API-Key: noti_your_key" \
  https://app.notifer.io/my-topic

Odpowiedź:

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1699000000

Rozwiązywanie problemów

401 Unauthorized

Przyczyna: Nieprawidłowy lub brakujący klucz API

Rozwiązanie:

• Sprawdź, czy klucz jest poprawny (brak dodatkowych spacji)
• Sprawdź, czy klucz nie został unieważniony lub usunięty
• Upewnij się, że używasz poprawnego nagłówka: X-API-Key

403 Forbidden

Przyczyna: Niewystarczające uprawnienia

Rozwiązanie:

• Sprawdź, czy zakresy kluczy obejmują wymagane uprawnienie
• Sprawdź dostęp do tematu (tematy prywatne wymagają własności)
• Sprawdź limity szybkości

429 Too Many Requests

Przyczyna: Przekroczono limit szybkości

Rozwiązanie:

• Zaimplementuj wykładnicze wycofywanie
• Ulepsz do wyższego planu
• Rozłóż żądania w czasie
• Sprawdź nagłówek X-RateLimit-Reset dla czasu resetu

Przykłady

Skrypt shell z obsługą błędów

#!/bin/bash

API_KEY="${NOTIFER_API_KEY}"
TOPIC="server-alerts"

send_notification() {
  local message="$1"
  local priority="${2:-3}"

  response=$(curl -s -w "\n%{http_code}" \
    -d "$message" \
    -H "X-API-Key: $API_KEY" \
    -H "X-Priority: $priority" \
    "https://app.notifer.io/$TOPIC")

  http_code=$(echo "$response" | tail -n1)

  if [ "$http_code" -eq 200 ] || [ "$http_code" -eq 201 ]; then
    echo "✓ Notification sent"
    return 0
  else
    echo "✗ Failed with code $http_code"
    return 1
  fi
}

# Użycie
send_notification "Server backup completed" 3

Python z logiką ponownych prób

import os
import time
import requests
from typing import Optional

API_KEY = os.getenv("NOTIFER_API_KEY")
BASE_URL = "https://app.notifer.io"

def publish_with_retry(
    topic: str,
    message: str,
    max_retries: int = 3
) -> Optional[dict]:
    """Publikuj wiadomość z wykładniczym wycofywaniem."""

    headers = {"X-API-Key": API_KEY}
    url = f"{BASE_URL}/{topic}"

    for attempt in range(max_retries):
        try:
            response = requests.post(
                url,
                data=message,
                headers=headers,
                timeout=10
            )

            if response.status_code in [200, 201]:
                return response.json()

            if response.status_code == 429:
                # Ograniczenie szybkości - czekaj i spróbuj ponownie
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue

            # Inny błąd - nie ponawiaj
            response.raise_for_status()

        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Wykładnicze wycofywanie

    return None

# Użycie
publish_with_retry("alerts", "Test message")

Porównanie z tokenami dostępu do tematu

Szczegółowe porównanie kluczy API z tokenami dostępu do tematów oraz wskazówki, kiedy używać każdej metody, znajdziesz w Uwierzytelnianie.

Następne kroki

• Tokeny dostępu do tematu - Uwierzytelnianie w zakresie tematu
• Tematy prywatne - Zabezpiecz swoje powiadomienia
• Publikowanie HTTP - Przykłady publikowania
• Uwierzytelnianie - Przegląd uwierzytelniania