Uwierzytelnianie

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

Metody uwierzytelniania

1. Publiczne tematy (tylko odczyt)

Publiczne tematy pozwalają na subskrybowanie i odczyt wiadomości bez uwierzytelniania:

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

Publikowanie wymaga uwierzytelniania

Nawet dla publicznych tematów, publikowanie wiadomości zawsze wymaga uwierzytelniania (JWT, klucz API lub token tematu). Tylko odczyt/subskrybowanie publicznych tematów jest otwarte.

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",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "username"
  }
}

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 30 minutach
• Token odświeżania: Wygasa po 7 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",
    "access_level": "read_write",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Odpowiedź:

{
  "id": "uuid",
  "token": "tk_abc123...",
  "name": "External Service",
  "access_level": "read_write",
  "can_read": true,
  "can_write": true,
  "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..."

Poziomy dostępu

• read - Subskrybowanie wiadomości, przeglądanie historii
• write - Tylko publikowanie wiadomości
• read_write - Odczyt i publikowanie

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	Odczyt publicznych tematów	Pojedynczy temat (tylko odczyt)	-
JWT	Akcje użytkownika, aplikacje web/mobilne	Pełne konto	30min (dostęp), 7d (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: 10 wiadomości/minutę
  • ESSENTIALS: 30 wiadomości/minutę
  • TEAM: 100 wiadomości/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:

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