Tokeny dostępu do tematu¶

Tokeny dostępu do tematu zapewniają uwierzytelnianie w zakresie dla publikowania do konkretnych tematów prywatnych.

Klucze API vs Tokeny dostępu do tematu

Nie wiesz, którego użyć?

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

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

Przegląd¶

Dlaczego warto używać tokenów dostępu do tematu?

Zakres tematu - Działa tylko dla konkretnego tematu
Bezpieczny - Ograniczone uprawnienia (tylko publikowanie lub tylko subskrypcja)
Możliwy do udostępnienia - Bezpieczny do udostępnienia usługom zewnętrznym
Możliwy do unieważnienia - Unieważnij bez wpływu na inne integracje
Możliwy do śledzenia - Monitoruj użycie dla każdego tokenu

Idealny dla:

Pipelinów CI/CD powiadamiających pojedynczy temat
Integracji zewnętrznych (narzędzia monitorujące, systemy alertów)
Udostępniania dostępu do tematu współpracownikom bez udostępniania danych uwierzytelniających konta
Automatycznych skryptów publikujących do jednego tematu

Tworzenie tokenów dostępu do tematu¶

Przez panel webowy¶

Przejdź do strony swojego tematu (np. app.notifer.io/topic/my-topic)
Kliknij Ustawienia tematu (ikona koła zębatego)
Przejdź do zakładki Tokeny dostępu
Kliknij Utwórz token
Wprowadź nazwę tokenu (np. "Pipeline CI")
Wybierz uprawnienia: publish, subscribe lub oba
Kliknij Utwórz
Skopiuj token (wyświetlany tylko raz!)

Przez API¶

# Utwórz token tylko do publikowania
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": "CI Pipeline Token",
    "permissions": ["publish"]
  }'

Odpowiedź:

{
  "id": "token_abc123",
  "token": "tk_FjZTOcx14k4_Kg6RtUCikAPYc2KNjXIMkWQUvDSREFc",
  "name": "CI Pipeline Token",
  "topic": "my-topic",
  "permissions": ["publish"],
  "created_at": "2025-11-10T10:00:00Z",
  "last_used_at": null
}

Zapisz swój token

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

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

W żądaniach HTTP (zalecane)¶

Użyj nagłówka X-Topic-Token:

curl -d "Kompilacja zakończona pomyślnie" \
  -H "X-Topic-Token: tk_FjZTOcx14k4_Kg6RtUCikAPYc2KNjXIMkWQUvDSREFc" \
  -H "X-Title: CI/CD" \
  -H "X-Priority: 3" \
  https://app.notifer.io/my-topic

Jako parametr zapytania¶

Dla narzędzi, które nie obsługują niestandardowych nagłówków:

curl -d "Kompilacja zakończona" \
  "https://app.notifer.io/my-topic?token=tk_FjZTOcx14k4_Kg6RtUCikAPYc2KNjXIMkWQUvDSREFc"

W Python¶

import requests

TOKEN = "tk_FjZTOcx14k4_Kg6RtUCikAPYc2KNjXIMkWQUvDSREFc"

response = requests.post(
    "https://app.notifer.io/my-topic",
    data="Build completed",
    headers={
        "X-Topic-Token": TOKEN,
        "X-Title": "CI/CD",
        "X-Priority": "3"
    }
)

W JavaScript¶

const TOKEN = 'tk_FjZTOcx14k4_Kg6RtUCikAPYc2KNjXIMkWQUvDSREFc';

fetch('https://app.notifer.io/my-topic', {
  method: 'POST',
  headers: {
    'X-Topic-Token': TOKEN,
    'X-Title': 'CI/CD',
    'Content-Type': 'text/plain'
  },
  body: 'Build completed'
});

Uprawnienia tokenu¶

Kontroluj, co każdy token może robić:

Uprawnienie	Opis	Przypadek użycia
`publish`	Publikuj wiadomości do tematu	Powiadomienia CI/CD, alerty monitorowania
`subscribe`	Subskrybuj wiadomości tematu	Agregacja logów, panele monitoringu
`publish,subscribe`	Zarówno publikuj, jak i subskrybuj	Pełny dostęp do integracji

Przykłady uprawnień¶

Tylko publikowanie (najczęstsze)Tylko subskrypcjaOba uprawnienia

# Pipeline CI/CD - wymaga tylko wysyłania powiadomień
curl -X POST https://app.notifer.io/api/topics/deployments/access-tokens \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Actions",
    "permissions": ["publish"]
  }'

# Usługa zewnętrzna konsumująca wiadomości
curl -X POST https://app.notifer.io/api/topics/events/access-tokens \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Log Aggregator",
    "permissions": ["subscribe"]
  }'

# Pełny dostęp do integracji
curl -X POST https://app.notifer.io/api/topics/monitoring/access-tokens \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monitoring Service",
    "permissions": ["publish", "subscribe"]
  }'

Zarządzanie tokenami¶

Wyświetl tokeny dla tematu¶

curl https://app.notifer.io/api/topics/my-topic/access-tokens \
  -H "Authorization: Bearer YOUR_JWT"

Unieważnij token¶

curl -X DELETE https://app.notifer.io/api/topics/my-topic/access-tokens/token_abc123 \
  -H "Authorization: Bearer YOUR_JWT"

Po unieważnieniu:

Token natychmiast przestaje działać
Wszystkie żądania z tym tokenem zwracają 401 Unauthorized
Tokenu nie można ponownie włączyć (zamiast tego utwórz nowy)

Monitoruj użycie tokenu¶

Wyświetl w ustawieniach tematu:

Ostatnie użycie - Kiedy token był ostatnio używany
Całkowite żądania - Liczba żądań wykonanych z tym tokenem
Utworzony przez - Użytkownik, który utworzył token

Porównanie z kluczami API¶

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

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

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

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)

Najlepsze praktyki bezpieczeństwa¶

Przechowywanie¶

Rób:

Przechowuj tokeny w zmiennych środowiskowych
Używaj przechowywania sekretów CI/CD (GitHub Secrets, GitLab CI Variables)
Używaj menedżerów sekretów (AWS Secrets Manager, HashiCorp Vault)
Twórz oddzielne tokeny dla każdej integracji
Unieważniaj nieużywane tokeny

Nie rób:

Nie commituj tokenów do kontroli wersji
Nie udostępniaj tokenów w postaci zwykłego tekstu (e-mail, Slack)
Nie używaj tego samego tokenu w wielu usługach
Nie przyznawaj więcej uprawnień niż potrzeba (np. publikowanie+subskrypcja, gdy potrzeba tylko publikowania)

Zmienne środowiskowe¶

# Przechowuj w pliku .env (dodaj do .gitignore!)
NOTIFER_TOPIC_TOKEN=tk_FjZTOcx14k4_Kg6RtUCikAPYc2KNjXIMkWQUvDSREFc

# Załaduj w skrypcie
source .env
curl -H "X-Topic-Token: $NOTIFER_TOPIC_TOKEN" \
  -d "Message" \
  https://app.notifer.io/my-topic

GitHub Actions¶

# Przechowuj token w sekretach repozytorium
- name: Notify deployment
  run: |
    curl -d "Deploy completed" \
      -H "X-Topic-Token: ${{ secrets.NOTIFER_TOPIC_TOKEN }}" \
      -H "X-Title: Deployment" \
      https://app.notifer.io/deployments

Docker Secrets¶

# Utwórz sekret
echo "tk_..." | docker secret create notifer_token -

# Użyj w docker-compose.yml
services:
  app:
    secrets:
      - notifer_token
    environment:
      NOTIFER_TOKEN_FILE: /run/secrets/notifer_token

secrets:
  notifer_token:
    external: true

Przykłady z rzeczywistych sytuacji¶

GitHub Actions CI/CD¶

name: Deploy and Notify

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy
        run: ./deploy.sh

      - name: Notify success
        if: success()
        run: |
          curl -d "Wdrożenie na produkcję powiodło się ✅" \
            -H "X-Topic-Token: ${{ secrets.NOTIFER_TOPIC_TOKEN }}" \
            -H "X-Title: Deploy Success" \
            -H "X-Priority: 3" \
            -H "X-Tags: ci,deploy,success" \
            https://app.notifer.io/deployments

      - name: Notify failure
        if: failure()
        run: |
          curl -d "Wdrożenie na produkcję nie powiodło się ❌" \
            -H "X-Topic-Token: ${{ secrets.NOTIFER_TOPIC_TOKEN }}" \
            -H "X-Title: Deploy Failed" \
            -H "X-Priority: 5" \
            -H "X-Tags: ci,deploy,error" \
            https://app.notifer.io/deployments

Skrypt monitorowania serwera¶

#!/bin/bash

TOPIC_TOKEN="tk_FjZTOcx14k4_Kg6RtUCikAPYc2KNjXIMkWQUvDSREFc"
TOPIC="server-alerts"

# Sprawdź miejsce na dysku
USAGE=$(df -h / | awk 'NR==2 {print $5}' | sed 's/%//')

if [ "$USAGE" -gt 90 ]; then
  PRIORITY=5
  MESSAGE="🚨 KRYTYCZNE: Użycie dysku na poziomie ${USAGE}%"
elif [ "$USAGE" -gt 80 ]; then
  PRIORITY=4
  MESSAGE="⚠️ OSTRZEŻENIE: Użycie dysku na poziomie ${USAGE}%"
else
  exit 0
fi

curl -d "$MESSAGE" \
  -H "X-Topic-Token: $TOPIC_TOKEN" \
  -H "X-Priority: $PRIORITY" \
  -H "X-Tags: server,disk,monitoring" \
  "https://app.notifer.io/$TOPIC"

Powiadomienie o kopii zapasowej bazy danych¶

#!/bin/bash

TOKEN="tk_your_token_here"
TOPIC="backups"

# Wykonaj kopię zapasową
if pg_dump production_db > /backups/db_$(date +%Y%m%d).sql; then
  # Powiadomienie o sukcesie
  curl -d "Kopia zapasowa bazy danych zakończona: $(date)" \
    -H "X-Topic-Token: $TOKEN" \
    -H "X-Title: Backup Success" \
    -H "X-Priority: 3" \
    -H "X-Tags: database,backup,success" \
    "https://app.notifer.io/$TOPIC"
else
  # Powiadomienie o niepowodzeniu
  curl -d "Kopia zapasowa bazy danych NIE POWIODŁA SIĘ: $(date)" \
    -H "X-Topic-Token: $TOKEN" \
    -H "X-Title: Backup Failed" \
    -H "X-Priority: 5" \
    -H "X-Tags: database,backup,error" \
    "https://app.notifer.io/$TOPIC"
fi

Rozwiązywanie problemów¶

401 Unauthorized¶

Przyczyna: Nieprawidłowy lub brakujący token

Rozwiązanie:

Sprawdź, czy token jest poprawny (brak dodatkowych spacji lub nowych linii)
Sprawdź, czy token nie został unieważniony
Upewnij się, że używasz poprawnego nagłówka: X-Topic-Token (nie X-API-Key)
Potwierdź, że token jest dla poprawnego tematu

403 Forbidden¶

Przyczyna: Brak wymaganego uprawnienia tokenu

Rozwiązanie:

Sprawdź, czy token ma uprawnienie publish dla żądań POST/PUT
Sprawdź, czy token ma uprawnienie subscribe dla połączeń SSE/WebSocket
Sprawdź, czy temat jest nadal prywatny (token działa tylko dla tematów prywatnych)

Token wyświetla się jako nigdy nieużywany¶

Przyczyna: Token nie jest wysyłany poprawnie

Rozwiązanie:

Sprawdź nazwę nagłówka: X-Topic-Token (rozróżniana wielkość liter)
Sprawdź, czy nginx przekazuje nagłówek (zobacz konfiguracja nginx)
Przetestuj z curl szczegółowo: curl -v ...

Konfiguracja Nginx¶

Jeśli uruchamiasz własny proxy nginx, upewnij się, że przekazuje nagłówek X-Topic-Token:

location ~ ^/[a-zA-Z0-9_-]+$ {
    proxy_pass http://backend:8000;

    # Wymagane: Przekaż nagłówki uwierzytelniania
    proxy_set_header X-Topic-Token $http_x_topic_token;
    proxy_set_header Authorization $http_authorization;

    # Przekaż również nagłówki wiadomości
    proxy_set_header X-Title $http_x_title;
    proxy_set_header X-Priority $http_x_priority;
    proxy_set_header X-Tags $http_x_tags;
}

Następne kroki¶

Klucze API - Uwierzytelnianie na poziomie użytkownika
Tematy prywatne - Prywatność tematu i kontrola dostępu
Publikowanie HTTP - Przykłady publikowania
Przegląd uwierzytelniania - Wszystkie metody uwierzytelniania