Zarządzanie kluczami API

API keys umożliwiają programatyczny dostęp do SGS Hub API dla automatyzacji i integracji.

Czym są API keys?

API Key to unikalny token autoryzacyjny który umożliwia dostęp do SGS Hub REST API bez logowania przez przeglądarkę.

Use cases:

🤖 Automatyzacja - Scripty do zarządzania serwerami
🔗 Integracje - Połączenie z zewnętrznymi systemami (Discord boty, dashboardy)
📊 Monitoring - Zbieranie metryk i statystyk
🔧 DevOps - CI/CD pipelines dla deployment serwerów
🎮 Custom panels - Własny frontend do zarządzania

Przykład użycia:

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://sgshub.eu/api/servers

Tworzenie API key

Wymagania

✅ Aktywne konto SGS Hub
✅ Plan Starter lub wyższy (Free nie ma dostępu do API)
✅ Zweryfikowany email

Proces tworzenia

Krok 1: Otwórz Wellness Dashboard

Dashboard → Wellness (🔑 ikona w nawigacji)
Zakładka API Keys

Krok 2: Utwórz nowy key

Kliknij Create API Key
Formularz utworzenia:

Nazwa (Name):

Opisowa nazwa (np. "Discord Bot", "Monitoring Script", "CI/CD Pipeline")
3-50 znaków
Pomaga zidentyfikować cel klucza

Opis (Description) - opcjonalny:

Dodatkowe informacje
Przykład: "Discord bot do sprawdzania statusu serwerów w kanale #status"

Uprawnienia (Permissions): Wybierz poziom dostępu:

Read Only - Tylko odczyt (GET requests)
Read + Write - Odczyt i modyfikacja (GET, POST, PATCH)
Full Access - Wszystkie operacje (GET, POST, PATCH, DELETE)

Principle of Least Privilege

Nadawaj minimalny poziom uprawnień potrzebny do działania. Jeśli skrypt tylko sprawdza status - wystarczy Read Only. Full Access tylko gdy absolutnie konieczne!

Scope (Zakres): Wybierz zasoby do których key ma dostęp:

☐ Servers (serwery)
☐ Mods (mody)
☐ Backups (kopie zapasowe)
☐ Schedules (harmonogramy)
☐ Community (gildie, eventy)
☐ Wellness (statystyki, usage)

Rate Limit:

Default: 100 requests/minute
Pro plan: 500 requests/minute
Enterprise plan: 1000 requests/minute
Custom: Skontaktuj się z supportem

IP Whitelist - opcjonalny:

Lista adresów IP które mogą używać tego klucza
Format: 192.168.1.1 lub 192.168.1.0/24 (subnet)
Zwiększa bezpieczeństwo (key działa tylko z zaufanych IP)

Przykład:

203.0.113.50    # Production server
198.51.100.0/24 # Office network

Expiration (Wygaśnięcie) - opcjonalny:

30 days
90 days
1 year
Never (permanent)
Custom date

Używaj expiration dla temporary keys

Dla testowych lub tymczasowych integracji ustaw expiration. Zmniejsza ryzyko jeśli zapomnisz revoke key później.

Krok 3: Wygeneruj klucz

Kliknij Generate API Key
System wygeneruje unikalny klucz

Krok 4: WAŻNE - Skopiuj klucz!

🔑 Your API Key (shown only once):

sgsh_1234567890abcdefghijklmnopqrstuvwxyz_aBcDeF

⚠️ COPY THIS KEY NOW! It will NOT be shown again.

[Copy to Clipboard]

Klucz pokazywany tylko raz!

Po zamknięciu tego ekranu NIE BĘDZIESZ mógł ponownie zobaczyć klucza. Musisz go bezpiecznie zapisać lub wygenerować nowy.

Zapisz w bezpiecznym miejscu:

Password manager (LastPass, 1Password, Bitwarden)
Encrypted vault
Environment variables (.env file)

NIE zapisuj w:

Plain text files
Git repositories
Publicznych miejscach

Zarządzanie kluczami

Lista kluczy API

Wellness → API Keys

Zobaczysz wszystkie swoje klucze:

Nazwa	Created	Last Used	Requests (30d)	Rate Limit	Status	Actions
Discord Bot	2025-10-01	2 min ago	45,280	100/min	Active	Edit, Revoke
Monitoring	2025-09-15	1 day ago	12,500	100/min	Active	Edit, Revoke
Old Script	2025-08-01	Never	0	100/min	Inactive	Revoke

Kolumny:

Nazwa - Nazwa nadana przy tworzeniu
Created - Data utworzenia
Last Used - Ostatnie użycie (timestamp)
Requests (30d) - Liczba requestów ostatnie 30 dni
Rate Limit - Limit requests/minute
Status - Active / Inactive / Expired / Revoked
Actions - Edycja / Revoke

Sortowanie:

By name
By creation date
By last used (useful to find unused keys)
By request count

Edycja klucza

Co możesz zmienić:

✅ Nazwę i opis
✅ Uprawnienia i scope
✅ Rate limit
✅ IP whitelist
✅ Expiration date
❌ NIE możesz zmienić samego klucza (musisz wygenerować nowy)

Jak edytować:

Znajdź klucz na liście
Kliknij Edit
Zmień ustawienia
Kliknij Save
Zmiany wchodzą w życie natychmiast

Zmiana uprawnień

Jeśli zmniejszysz uprawnienia (np. Full Access → Read Only), aplikacje używające tego klucza mogą przestać działać. Upewnij się że wiesz co robisz!

Revoke (unieważnienie) klucza

Kiedy revoke:

✅ Klucz nie jest już używany
✅ Klucz został skompromitowany (leaked)
✅ Integracja została wyłączona
✅ Employee który używał klucza opuścił firmę
✅ Periodically (rotate keys co 90 dni)

Jak revoke:

Znajdź klucz
Kliknij Revoke

Potwierdź:

Czy na pewno chcesz revoke "Discord Bot" API key?

⚠️ OSTRZEŻENIE:
- Klucz przestanie działać natychmiast
- Wszystkie requesty z tym kluczem będą rejected (401 Unauthorized)
- Aplikacje używające tego klucza przestaną działać
- TA AKCJA NIE MOŻE BYĆ COFNIĘTA

[Cancel] [Revoke Key]

Klucz zostaje unieważniony

Po revoke:

Status zmienia się na "Revoked"
Klucz pozostaje na liście (dla audytu) ale nie działa
Można usunąć revoked keys (Delete button)

Regenerowanie klucza

**Jeśli zgubił

eś klucz lub chcesz go zmienić:**

Opcja 1: Revoke + Create New

Revoke stary klucz
Create nowy klucz z tymi samymi ustawieniami
Zaktualizuj aplikacje z nowym kluczem

Opcja 2: Rotate Key (nadchodzące) SGS Hub planuje funkcję "Rotate Key" która automatycznie:

Wygeneruje nowy klucz
Zachowa stary przez grace period (7 dni)
Po 7 dniach automatycznie revoke stary

Używanie API keys

Podstawowa autentykacja

Authorization header:

http

GET /api/servers HTTP/1.1
Host: sgshub.eu
Authorization: Bearer sgsh_1234567890abcdefghijklmnopqrstuvwxyz_aBcDeF

W cURL:

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://sgshub.eu/api/servers

W JavaScript/Node.js:

javascript

const axios = require('axios');

const apiKey = process.env.SGSHUB_API_KEY;

axios.get('https://sgshub.eu/api/servers', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

W Python:

python

import requests
import os

api_key = os.environ.get('SGSHUB_API_KEY')

headers = {
    'Authorization': f'Bearer {api_key}'
}

response = requests.get('https://sgshub.eu/api/servers', headers=headers)
print(response.json())

Przechowywanie kluczy bezpiecznie

Best practices:

1. Environment Variables

bash

# .env file (dodaj do .gitignore!)
SGSHUB_API_KEY=sgsh_1234567890abcdefghijklmnopqrstuvwxyz_aBcDeF

2. Secret Management Tools

AWS Secrets Manager
Azure Key Vault
Google Cloud Secret Manager
HashiCorp Vault

3. GitHub Secrets (CI/CD) Repository Settings → Secrets → New repository secret

4. Password Manager

LastPass, 1Password, Bitwarden
Secure notes lub custom fields

DON'T:

❌ Hard-code w kodzie źródłowym
❌ Commit do Git repository
❌ Dziel się przez email/chat
❌ Zapisuj w plain text files

Testowanie API key

Quick test w terminalu:

bash

# Zamień YOUR_API_KEY na swój klucz
export API_KEY="sgsh_1234567890..."

# Test połączenia
curl -H "Authorization: Bearer $API_KEY" \
     https://sgshub.eu/api/health

# Jeśli działa, zobaczysz:
{"status":"ok","message":"API is healthy"}

# Jeśli nie działa:
{"error":"Unauthorized","message":"Invalid API key"}

Test w Postman:

Nowy request → GET https://sgshub.eu/api/servers
Authorization tab → Type: Bearer Token
Token: Wklej swój API key
Send
Powinno zwrócić listę serwerów (200 OK)

Rate Limiting

Jak działa

Rate limit ogranicza liczbę requestów per minutę/godzinę.

Limity według planu:

Starter: 100 requests/minute, 1,000/hour
Pro: 500 requests/minute, 10,000/hour
Enterprise: 1,000 requests/minute, 50,000/hour

Per-key limits: Możesz ustawić custom limit per klucz (niższy niż plan limit).

Przykład:

Plan Pro: 500/min max
Production Bot key: 500/min
Test Script key: 50/min (custom limit niższy)

Response headers

Każdy API response zawiera rate limit headers:

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1698345600

Headers:

X-RateLimit-Limit - Twój limit (requests/minute)
X-RateLimit-Remaining - Pozostałe requesty w obecnym oknie
X-RateLimit-Reset - Unix timestamp kiedy limit się resetuje

Obsługa rate limit exceeded

Gdy przekroczysz limit:

http

HTTP/1.1 429 Too Many Requests
Retry-After: 45

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit of 100 requests per minute",
  "retryAfter": 45
}

Odpowiedź:

Status code: 429 Too Many Requests
Header Retry-After: Sekundy do poczekania
Body JSON z details

Jak obsłużyć w kodzie:

javascript

async function makeRequest(url) {
  try {
    const response = await axios.get(url, { headers });
    return response.data;
  } catch (error) {
    if (error.response.status === 429) {
      const retryAfter = error.response.data.retryAfter || 60;
      console.log(`Rate limited. Retrying after ${retryAfter}s`);
      await sleep(retryAfter * 1000);
      return makeRequest(url); // Retry
    }
    throw error;
  }
}

Strategia unikania rate limits

1. Cache responses Nie pytaj API za każdym razem - cache dane lokalnie:

javascript

const cache = {};
const CACHE_TTL = 60000; // 1 minuta

async function getServers() {
  if (cache.servers && Date.now() - cache.serversTime < CACHE_TTL) {
    return cache.servers; // Zwróć z cache
  }

  const servers = await api.getServers(); // Zapytaj API
  cache.servers = servers;
  cache.serversTime = Date.now();
  return servers;
}

2. Batch requests Zamiast 100 requestów po 1 item, 1 request po 100 items:

javascript

// ❌ Bad: 100 requests
for (const serverId of serverIds) {
  await api.getServer(serverId);
}

// ✅ Good: 1 request
const servers = await api.getServers({ ids: serverIds.join(',') });

3. Webhooks zamiast polling Zamiast sprawdzać co minutę czy coś się zmieniło, użyj webhooks (gdy dostępne).

4. Exponential backoff Gdy rate limited, czekaj coraz dłużej:

javascript

let delay = 1000; // Start z 1s
for (let attempt = 0; attempt < 5; attempt++) {
  try {
    return await makeRequest();
  } catch (error) {
    if (error.response.status === 429) {
      await sleep(delay);
      delay *= 2; // 1s, 2s, 4s, 8s, 16s
    }
  }
}

Bezpieczeństwo

IP Whitelisting

Zalecane dla production.

Jak skonfigurować:

Edit API key

IP Whitelist field:

203.0.113.50     # Single IP
198.51.100.0/24  # Subnet (256 IPs)
2001:db8::/32    # IPv6 subnet

Save

Efekt: Requesty z innych IP zostaną rejected:

http

HTTP/1.1 403 Forbidden
{
  "error": "IP not whitelisted",
  "message": "Your IP (192.0.2.100) is not allowed to use this API key"
}

Rotation Policy

Best practice: Rotuj klucze co 90 dni.

Proces:

Utwórz nowy klucz (z tymi samymi uprawnieniami)
Zaktualizuj produkcyjne aplikacje z nowym kluczem
Monitoruj przez 7 dni (czy aplikacje używają nowego)
Revoke stary klucz

Automatyzacja:

Ustaw reminder w kalendarzu (co 90 dni)
Lub włącz expiration przy tworzeniu klucza

Monitoring suspicious activity

Red flags:

⚠️ Nagły spike w requestach (możliwy leak)
⚠️ Requesty z nieznanych IP (gdy whitelist włączony)
⚠️ Wiele 401/403 errors (ktoś próbuje użyć klucza)
⚠️ Requesty poza normalnymi godzinami (jeśli aplikacja działa 9-17)

Gdzie sprawdzać: Wellness → Monitoring → API Usage (zobacz następną stronę)

Co robić gdy klucz leaked

Jeśli podejrzewasz że klucz został skompromitowany:

NATYCHMIAST revoke klucz
- Wellness → API Keys → [Key] → Revoke
Sprawdź logi użycia
- Monitoring → API Usage → Filtruj po tym kluczu
- Szukaj suspicious activity (nieznane IP, dziwne endpointy)
Wygeneruj nowy klucz
- Z nowymi credentials
Zaktualizuj aplikacje
- Wszystkie miejsca gdzie stary klucz był używany
Zresetuj hasło SGS Hub
- Jeśli podejrzewasz że konto jest skompromitowane
Zgłoś do supportu
- support@sgshub.eu z szczegółami

Troubleshooting

401 Unauthorized

Problem: API zwraca 401 Unauthorized

Przyczyny:

Klucz jest nieprawidłowy (typo, niepełny)
Klucz został revoked
Klucz expired
Brak Authorization header
Błędny format (np. brak "Bearer ")

Rozwiązanie:

Sprawdź czy klucz jest kompletny i poprawnie skopiowany
Sprawdź status klucza w Wellness → API Keys
Upewnij się że header format to: Authorization: Bearer YOUR_KEY

403 Forbidden

Problem: API zwraca 403 Forbidden

Przyczyny:

Twój IP nie jest na whitelist
Brak uprawnień dla tego endpoint (np. Read Only key próbuje POST)
Scope nie obejmuje tego zasobu

Rozwiązanie:

Sprawdź IP whitelist settings
Sprawdź permissions klucza (Read Only vs Full Access)
Sprawdź scope (czy servers checkbox zaznaczony dla /api/servers)

429 Too Many Requests

Problem: Zbyt wiele requestów

Rozwiązanie:

Poczekaj czas wskazany w Retry-After header
Implement caching
Implement exponential backoff
Rozważ upgrade planu (wyższy rate limit)

Klucz nie pojawia się po utworzeniu

Problem: Utworzyłem klucz ale nie widzę go na liście

Rozwiązanie:

Odśwież stronę (Ctrl+F5)
Sprawdź czy masz odpowiedni plan (Free nie obsługuje API)
Sprawdź czy klucz nie został automatycznie usunięty (błąd płatności za plan)

Best Practices

Do's ✅

✅ Jeden klucz per aplikacja - Łatwiej track usage i revoke
✅ Używaj IP whitelisting - Dodatkowa warstwa bezpieczeństwa
✅ Minimal permissions - Read Only jeśli write nie jest potrzebny
✅ Environment variables - Nie hard-code kluczy
✅ Monitor usage - Regularnie sprawdzaj Wellness → Monitoring
✅ Rotate regularly - Co 90 dni lub częściej
✅ Revoke unused keys - Zmniejsz attack surface

Don'ts ❌

❌ Nie commituj do Git - Zawsze .gitignore .env files
❌ Nie udostępniaj publicznie - Email, chat, forum
❌ Nie używaj jednego klucza wszędzie - Jeden leak = wszystko skompromitowane
❌ Nie ignoruj rate limits - Respect limits, implement backoff
❌ Nie dawaj Full Access bez potrzeby - Principle of least privilege
❌ Nie zapominaj o expiration - Dla temporary/test keys

Następne kroki

Monitoring - Śledzenie użycia API i metryk
Settings - Konfiguracja notyfikacji i preferencji
API Reference - Pełna dokumentacja endpointów API

Zarządzanie kluczami API ​

Czym są API keys? ​

Tworzenie API key ​

Wymagania ​

Proces tworzenia ​

Zarządzanie kluczami ​

Lista kluczy API ​

Edycja klucza ​

Revoke (unieważnienie) klucza ​

Regenerowanie klucza ​

Używanie API keys ​

Podstawowa autentykacja ​

Przechowywanie kluczy bezpiecznie ​

Testowanie API key ​

Rate Limiting ​

Jak działa ​

Response headers ​

Obsługa rate limit exceeded ​

Strategia unikania rate limits ​

Bezpieczeństwo ​

IP Whitelisting ​

Rotation Policy ​

Monitoring suspicious activity ​

Co robić gdy klucz leaked ​

Troubleshooting ​

401 Unauthorized ​

403 Forbidden ​

429 Too Many Requests ​

Klucz nie pojawia się po utworzeniu ​

Best Practices ​

Do's ✅ ​

Don'ts ❌ ​

Następne kroki ​

Zarządzanie kluczami API

Czym są API keys?

Tworzenie API key

Wymagania

Proces tworzenia

Zarządzanie kluczami

Lista kluczy API

Edycja klucza

Revoke (unieważnienie) klucza

Regenerowanie klucza

Używanie API keys

Podstawowa autentykacja

Przechowywanie kluczy bezpiecznie

Testowanie API key

Rate Limiting

Jak działa

Response headers

Obsługa rate limit exceeded

Strategia unikania rate limits

Bezpieczeństwo

IP Whitelisting

Rotation Policy

Monitoring suspicious activity

Co robić gdy klucz leaked

Troubleshooting

401 Unauthorized

403 Forbidden

429 Too Many Requests

Klucz nie pojawia się po utworzeniu

Best Practices

Do's ✅

Don'ts ❌

Następne kroki