Klucze API¶

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

Klucze API vs Tokeny dostępu do tematu

Nie wiesz, którego użyć?

Klucze API użytkownika (noti_...) - Działają we wszystkich Twoich tematach, do szerszej automatyzacji
Tokeny dostępu do tematu (tk_...) - Ograniczone do jednego tematu, zalecane dla integracji

👉 Dowiedz się więcej o różnicach

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¶

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

Przez CLI¶

notifer keys create my-script-key \
  --description "Automation script" \
  --scopes "publish,subscribe"

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": "key_abc123",
  "name": "my-script-key",
  "key": "noti_1234567890abcdefghijklmnopqrstuv",
  "scopes": ["publish", "subscribe"],
  "created_at": "2025-11-02T10:00:00Z"
}

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¶

W żądaniach HTTP¶

Użyj nagłówka X-API-Key:

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

W Python¶

import requests

headers = {
    "X-API-Key": "noti_your_key_here"
}

response = requests.post(
    "https://app.notifer.io/my-topic",
    data="Automated message",
    headers=headers
)

W JavaScript¶

fetch('https://app.notifer.io/my-topic', {
  method: 'POST',
  headers: {
    'X-API-Key': 'noti_your_key_here',
    'Content-Type': 'text/plain'
  },
  body: 'Automated message'
});

W CLI¶

# Ustaw w pliku konfiguracyjnym
notifer config set api-key noti_your_key_here

# Lub przekaż jako opcję
notifer publish my-topic "Message" --api-key noti_your_key_here

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
`keys:read`	Przeglądanie kluczy API	Skrypty audytowe
`keys:write`	Zarządzanie kluczami API	Automatyzacja administracyjna

Najlepsze praktyki dotyczące zakresów¶

Pipeline CI/CDSkrypt monitorującyAutomatyzacja administracyjna

# Wymaga tylko uprawnienia do publikowania
notifer keys create ci-pipeline \
  --scopes "publish"

# Wymaga uprawnień do odczytu i publikowania
notifer keys create monitoring \
  --scopes "publish,topics:read"

# Pełny dostęp
notifer keys create admin-script \
  --scopes "*"

Zarządzanie kluczami¶

Wyświetl wszystkie klucze¶

CLIAPI

notifer keys list

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ć):

CLIAPI

notifer keys revoke key_abc123

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

Usuń klucz¶

Trwale usuń klucz (nieodwracalne):

CLIAPI

notifer keys delete key_abc123

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

Wygaśnięcie klucza¶

Ustaw daty wygaśnięcia dla tymczasowego dostępu:

# Wygasa za 30 dni
notifer keys create temp-key \
  --expires "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¶

Zrozumienie, kiedy używać każdej metody uwierzytelniania:

Funkcja	Klucz API użytkownika (`noti_...`)	Token dostępu do tematu (`tk_...`)
Zakres	Wszystkie Twoje tematy	Tylko jeden temat
Prefix	`noti_...`	`tk_...`
Nagłówek	`X-API-Key`	`X-Topic-Token`
Uprawnienia	Zakresy globalne	Dla każdego tokenu (publikowanie/subskrypcja)
Najlepszy dla	Automatyzacji wielotematowej	Integracji specyficznych dla tematu
Udostępnianie	❌ Ryzykowne (pełny dostęp)	✅ Bezpieczne (ograniczony zakres)
Wpływ unieważnienia	Wpływa na wszystkie integracje	Wpływa tylko na jeden temat
Tworzony przez	Ustawienia konta	Ustawienia tematu
Przykładowe użycie	Skrypty administracyjne, panele	CI/CD dla jednego tematu

Kiedy używać kluczy API¶

✅ Używaj kluczy API, gdy:

Budujesz automatyzację działającą w wielu tematach
Tworzysz skrypty administracyjne lub panele
Kontrolujesz całą integrację
Potrzebujesz uprawnień do zarządzania tematami (tworzenie, usuwanie tematów)
Potrzebujesz globalnego dostępu do swojego konta

Kiedy używać tokenów dostępu do tematu¶

✅ Używaj tokenów dostępu do tematu, gdy:

Integrujesz z usługami zewnętrznymi (GitHub Actions, narzędzia monitorujące)
Każda integracja powinna mieć dostęp tylko do jednego tematu
Chcesz udostępnić dostęp bez udostępniania danych uwierzytelniających konta
Potrzebujesz szczegółowej kontroli uprawnień dla każdego tematu
Chcesz łatwo unieważnić dostęp dla jednej integracji

👉 Dowiedz się więcej o tokenach dostępu do tematu

Następne kroki¶

Tokeny dostępu do tematu - Uwierzytelnianie w zakresie tematu
Tematy prywatne - Zabezpiecz swoje powiadomienia
Publikowanie HTTP - Przykłady publikowania
Narzędzie CLI - Zarządzaj kluczami z linii poleceń
Uwierzytelnianie - Przegląd uwierzytelniania