Uwierzytelnianie¶

Notifer obsługuje wiele metod uwierzytelniania w zależności od przypadku użycia.

Metody uwierzytelniania¶

1. Brak uwierzytelniania (publiczne tematy)¶

Publiczne tematy nie wymagają uwierzytelniania do publikowania lub subskrybowania:

# Publikowanie do publicznego tematu
curl -d "Hello World" https://app.notifer.io/my-public-topic

# Subskrybowanie publicznego tematu
curl -N https://app.notifer.io/my-public-topic/sse

2. Tokeny JWT (uwierzytelnianie użytkownika)¶

Używane do: - Tworzenia/zarządzania tematami - Dostępu do prywatnych tematów - Zarządzania kontem - Pełnego dostępu do API

Uzyskiwanie tokenu JWT¶

Logowanie przez email/hasło:

curl -X POST https://app.notifer.io/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Odpowiedź:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400
}

Google OAuth:

# Przekieruj użytkownika do:
https://app.notifer.io/auth/google

# Po przepływie OAuth otrzymasz tokeny JWT

Używanie tokenów JWT¶

Format nagłówka:

curl https://app.notifer.io/api/topics \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Parametr zapytania (tylko SSE/WebSocket):

# Dla subskrypcji SSE
curl -N "https://app.notifer.io/my-private-topic/sse?token=YOUR_ACCESS_TOKEN"

# Dla połączeń WebSocket
wscat -c "wss://app.notifer.io/my-private-topic/ws?token=YOUR_ACCESS_TOKEN"

Wygaśnięcie tokenu¶

Token dostępu: Wygasa po 24 godzinach
Token odświeżania: Wygasa po 30 dniach

Odświeżanie tokenów:

curl -X POST https://app.notifer.io/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

3. Klucze API (uwierzytelnianie skryptów)¶

Klucze API to długo-żyjące tokeny dla skryptów i integracji.

Tworzenie klucza API¶

Przez aplikację webową: 1. Przejdź do Ustawienia → Klucze API 2. Kliknij "Utwórz klucz API" 3. Wprowadź nazwę (np. "Serwer produkcyjny") 4. Skopiuj klucz (pokazany 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": "Production Server",
    "expires_at": null
  }'

Odpowiedź:

{
  "id": "uuid",
  "key": "noti_abc123...",
  "name": "Production Server",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": null,
  "last_used_at": null
}

Używanie kluczy API¶

Format nagłówka:

curl -d "Server is down!" \
  -H "X-API-Key: noti_abc123..." \
  https://app.notifer.io/alerts

Parametr zapytania:

curl -d "Message" "https://app.notifer.io/alerts?api_key=noti_abc123..."

Funkcje kluczy API¶

✅ Długo-żyjące (domyślnie bez wygaśnięcia)
✅ Mogą być nazwane dla łatwej identyfikacji
✅ Mogą być w każdej chwili odwołane
✅ Śledzenie znacznika czasu ostatniego użycia
✅ Działają dla wszystkich punktów końcowych API
⚠️ Pełny dostęp do konta (używaj ostrożnie!)

Najlepsze praktyki¶

Nazywaj swoje klucze - Używaj opisowych nazw (np. "CI/CD Pipeline", "Monitoring Server")
Rotuj regularnie - Twórz nowe klucze i odwołuj stare okresowo
Jeden klucz na usługę - Nie udostępniaj kluczy między wieloma usługami
Odwołuj nieużywane klucze - Usuwaj klucze, których już nie używasz
Używaj zmiennych środowiskowych - Nigdy nie commituj kluczy do kontroli wersji

4. Tokeny dostępu do tematów (uwierzytelnianie z zakresem tematu)¶

Tokeny dostępu do tematów zapewniają ograniczony dostęp do pojedynczego tematu.

Tworzenie tokenu dostępu do tematu¶

Przez aplikację webową: 1. Przejdź do strony tematu 2. Kliknij Ustawienia → Tokeny dostępu 3. Kliknij "Utwórz token" 4. Wybierz uprawnienia (odczyt/zapis) 5. Ustaw wygaśnięcie (opcjonalnie)

Przez API:

curl -X POST https://app.notifer.io/api/topics/my-topic/access-tokens \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "External Service",
    "permissions": ["read", "write"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Odpowiedź:

{
  "id": "uuid",
  "token": "tk_abc123...",
  "name": "External Service",
  "permissions": ["read", "write"],
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2025-12-31T23:59:59Z"
}

Używanie tokenów dostępu do tematów¶

Publikowanie:

curl -d "Message from external service" \
  -H "X-Topic-Token: tk_abc123..." \
  https://app.notifer.io/my-topic

Subskrybowanie:

curl -N "https://app.notifer.io/my-topic/sse?token=tk_abc123..."

Uprawnienia¶

read - Subskrybowanie wiadomości, przeglądanie historii
write - Publikowanie wiadomości

Kiedy używać tokenów tematów vs kluczy API¶

Funkcja	Token tematu	Klucz API
Zakres	Pojedynczy temat	Wszystkie tematy
Uprawnienia	Odczyt/Zapis na token	Pełny dostęp
Wygaśnięcie	Opcjonalne	Opcjonalne
Przypadek użycia	Dostęp zewnętrzny	Własne skrypty
Bezpieczeństwo	Ograniczony zasięg szkód	Pełny dostęp do konta

Rekomendacja: Używaj tokenów dostępu do tematów do udzielania ograniczonego dostępu zewnętrznym usługom lub niezaufanym środowiskom.

Porównanie uwierzytelniania¶

Metoda	Przypadek użycia	Zakres	Wygaśnięcie
Brak	Publiczne tematy	Pojedynczy temat	-
JWT	Akcje użytkownika, aplikacje web/mobilne	Pełne konto	24h (dostęp), 30d (odświeżenie)
Klucz API	Skrypty, CI/CD, serwery	Pełne konto	Opcjonalne
Token tematu	Usługi zewnętrzne, ograniczony dostęp	Pojedynczy temat	Opcjonalne

Najlepsze praktyki bezpieczeństwa¶

Dla tokenów JWT¶

✅ Przechowuj bezpiecznie (nigdy w localStorage dla aplikacji webowych)
✅ Używaj tylko HTTPS
✅ Odświeżaj przed wygaśnięciem
✅ Implementuj rotację tokenów

Dla kluczy API¶

✅ Przechowuj w zmiennych środowiskowych lub menedżerach sekretów
✅ Nigdy nie commituj do kontroli wersji
✅ Używaj plików .env z .gitignore
✅ Rotuj okresowo (np. co 90 dni)
✅ Odwołaj natychmiast w przypadku naruszenia

Dla tokenów tematów¶

✅ Ustawiaj daty wygaśnięcia gdy to możliwe
✅ Przyznawaj minimalne wymagane uprawnienia (tylko do odczytu gdy to możliwe)
✅ Odwołuj gdy nie są już potrzebne
✅ Monitoruj użycie przez last_used_at

Przykłady kodu¶

Python z JWT¶

import requests

# Logowanie
response = requests.post('https://app.notifer.io/auth/login', json={
    'email': 'user@example.com',
    'password': 'password'
})
token = response.json()['access_token']

# Użycie tokenu
headers = {'Authorization': f'Bearer {token}'}
requests.post('https://app.notifer.io/my-topic',
              data='Hello', headers=headers)

Python z kluczem API¶

import requests
import os

# Wczytanie ze zmiennej środowiskowej
API_KEY = os.environ['NOTIFER_API_KEY']

# Publikowanie
requests.post('https://app.notifer.io/alerts',
              data='Server alert!',
              headers={'X-API-Key': API_KEY})

JavaScript/Node.js z JWT¶

const axios = require('axios');

// Logowanie
const { data } = await axios.post('https://app.notifer.io/auth/login', {
  email: 'user@example.com',
  password: 'password'
});

const token = data.access_token;

// Użycie tokenu
await axios.post('https://app.notifer.io/my-topic',
  'Hello',
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
);

Bash z kluczem API¶

# Przechowywanie w zmiennej środowiskowej
export NOTIFER_API_KEY="noti_abc123..."

# Publikowanie
curl -d "Deployment complete" \
  -H "X-API-Key: $NOTIFER_API_KEY" \
  https://app.notifer.io/deploys

Odpowiedzi błędów¶

401 Unauthorized¶

Brak tokenu:

{
  "detail": "Not authenticated"
}

Nieprawidłowy token:

{
  "detail": "Could not validate credentials"
}

Wygasły token:

{
  "detail": "Token has expired"
}

403 Forbidden¶

Niewystarczające uprawnienia:

{
  "detail": "Insufficient permissions to access this topic"
}

Ograniczanie częstotliwości¶

Uwierzytelnianie wpływa na limity częstotliwości:

Nieuwierzytelniony: 60 żądań/minutę na IP
Uwierzytelniony (JWT/Klucz API): Różni się w zależności od planu subskrypcji
Free: 60 żądań/minutę
Pro: 300 żądań/minutę
Team: 600 żądań/minutę

Następne kroki¶

Przegląd API - Poznaj dostępne punkty końcowe
Dokumentacja API - Kompletna dokumentacja punktów końcowych
Przewodnik kluczy API - Szczegółowe zarządzanie kluczami API
Tokeny dostępu do tematów - Uwierzytelnianie z zakresem tematu
Prywatne tematy - Konfiguracja kontroli dostępu

Wsparcie¶

Jeśli masz problemy z uwierzytelnianiem:

Sprawdź czy Twój token nie wygasł
Zweryfikuj że używasz poprawnego formatu nagłówka
Upewnij się że używasz HTTPS (nie HTTP) dla produkcji
Skontaktuj się ze wsparciem: support@notifer.io