Uwierzytelnianie

Dowiedz się jak bezpiecznie uwierzytelniać żądania do SGS Hub API.

Przegląd

SGS Hub API używa kluczy API (API Keys) do uwierzytelniania żądań.

Metoda: Bearer Token Authentication (RFC 6750)

http

GET /api/servers HTTP/1.1
Host: sgshub.eu
Authorization: Bearer sgshub_sk_live_abc123def456ghi789jkl012mno345pqr678stu901
Content-Type: application/json

Tworzenie klucza API

Przez Dashboard

Zaloguj się do SGS Hub
Dashboard → Wellness → API Keys
Kliknij "Create API Key"
Wypełnij formularz:
- Name (wymagane): np. "Production Server Bot"
- Permission Level (wymagane): Read Only / Read+Write / Full Access
- Scopes (opcjonalne): wybierz konkretne zakresy
- IP Whitelist (opcjonalne): ogranicz do konkretnych IP
- Expiration (opcjonalne): data wygaśnięcia klucza
Kliknij "Generate API Key"
Skopiuj klucz - zostanie pokazany tylko raz!

Przykładowy klucz:

sgshub_sk_live_abc123def456ghi789jkl012mno345pqr678stu901

Jednorazowe wyświetlenie

Po zamknięciu modalu klucz NIE będzie widoczny ponownie. Zapisz go w bezpiecznym miejscu (menedżer haseł, vault).

Przez API

Możesz też utworzyć klucz programatycznie (wymaga istniejącego klucza z zakresem api-keys:write):

bash

curl -X POST https://sgshub.eu/api/wellness/api-keys \
  -H "Authorization: Bearer YOUR_EXISTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Automated Key",
    "permissionLevel": "READ_WRITE",
    "scopes": ["servers:read", "servers:write", "mods:read"],
    "expiresAt": "2026-01-01T00:00:00Z"
  }'

Response (201 Created):

json

{
  "data": {
    "id": "key_xyz789",
    "name": "Automated Key",
    "key": "sgshub_sk_live_new123key456...",
    "permissionLevel": "READ_WRITE",
    "scopes": ["servers:read", "servers:write", "mods:read"],
    "createdAt": "2025-10-26T15:30:00Z",
    "expiresAt": "2026-01-01T00:00:00Z"
  }
}

Format klucza

Klucze API SGS Hub mają strukturę:

sgshub_{type}_{env}_{random}

Część	Opis	Przykład
`sgshub_`	Prefix (zawsze)	`sgshub_`
`{type}`	Typ klucza	`sk` (secret key)
`{env}`	Środowisko	`live` (produkcja) lub `test` (sandbox)
`{random}`	Losowy ciąg 48 znaków	`abc123def456...`

Przykłady:

sgshub_sk_live_abc123def456ghi789jkl012mno345pqr678stu901  (produkcja)
sgshub_sk_test_xyz789uvw456rst123opq890lmn567jkl234hij901  (sandbox)

Poziomy uprawnień

Read Only

Zakres: Tylko GET requests Przykład użycia: Monitorowanie, dashboardy, raporty

Dozwolone operacje:

✅ GET /api/servers
✅ GET /api/servers/{id}
✅ GET /api/servers/{id}/mods
❌ POST /api/servers (403 Forbidden)
❌ DELETE /api/servers/{id} (403 Forbidden)

Kody błędów:

403 Forbidden przy próbie POST/PATCH/DELETE
401 Unauthorized jeśli klucz nieprawidłowy

Read + Write

Zakres: GET, POST, PATCH, PUT Przykład użycia: Automatyzacja, integracje, boty Discord

Dozwolone operacje:

✅ GET /api/servers
✅ POST /api/servers
✅ PATCH /api/servers/{id}
✅ POST /api/servers/{id}/mods
❌ DELETE /api/servers/{id} (403 Forbidden - wymaga Full Access)

Ograniczenia:

Nie może usuwać zasobów (DELETE)
Nie może zmieniać ustawień konta

Full Access

Zakres: Wszystkie metody HTTP (GET, POST, PATCH, PUT, DELETE) Przykład użycia: Administracja, CLI tools, pełna automatyzacja

Dozwolone operacje:

✅ GET /api/servers
✅ POST /api/servers
✅ PATCH /api/servers/{id}
✅ DELETE /api/servers/{id}
✅ DELETE /api/wellness/api-keys/{id} (może usuwać inne klucze)

Bezpieczeństwo

Full Access ma nieograniczone uprawnienia - używaj tylko gdy konieczne. Dla większości integracji wystarczy Read+Write.

Zakresy (Scopes)

Scopes pozwalają precyzyjnie kontrolować dostęp do konkretnych zasobów.

Dostępne zakresy

Scope	Opis	Przykładowe endpointy
`servers:read`	Odczyt serwerów	GET /servers, GET /servers/
`servers:write`	Tworzenie/edycja serwerów	POST /servers, PATCH /servers/
`servers:delete`	Usuwanie serwerów	DELETE /servers/
`servers:power`	Kontrola zasilania	POST /servers/{id}/power
`mods:read`	Odczyt modów	GET /servers/{id}/mods
`mods:write`	Instalacja/usuwanie modów	POST /servers/{id}/mods
`files:read`	Odczyt plików	GET /servers/{id}/files
`files:write`	Upload/edycja plików	POST /servers/{id}/files
`backups:read`	Odczyt backupów	GET /servers/{id}/backups
`backups:write`	Tworzenie backupów	POST /servers/{id}/backups
`backups:restore`	Przywracanie backupów	POST /servers/{id}/backups/{id}/restore
`schedules:read`	Odczyt harmonogramów	GET /servers/{id}/schedules
`schedules:write`	CRUD harmonogramów	POST /servers/{id}/schedules
`community:read`	Odczyt gildii/eventów	GET /community/guilds
`community:write`	Zarządzanie społecznością	POST /community/guilds
`api-keys:read`	Lista kluczy API	GET /wellness/api-keys
`api-keys:write`	Tworzenie kluczy API	POST /wellness/api-keys
`api-keys:delete`	Usuwanie kluczy API	DELETE /wellness/api-keys/
`subscription:read`	Odczyt subskrypcji	GET /user/subscription
`subscription:write`	Zmiana planu	POST /user/subscription/upgrade

Mapowanie poziomów → scopes

Read Only:

json

{
  "scopes": [
    "servers:read",
    "mods:read",
    "files:read",
    "backups:read",
    "schedules:read",
    "community:read",
    "subscription:read"
  ]
}

Read + Write:

json

{
  "scopes": [
    "servers:read",
    "servers:write",
    "servers:power",
    "mods:read",
    "mods:write",
    "files:read",
    "files:write",
    "backups:read",
    "backups:write",
    "backups:restore",
    "schedules:read",
    "schedules:write",
    "community:read",
    "community:write"
  ]
}

Full Access:

json

{
  "scopes": ["*"]  // Wszystkie zakresy
}

Custom scopes

Możesz wybrać tylko potrzebne zakresy:

Przykład - Bot Discord do startu/stopu serwerów:

json

{
  "name": "Discord Bot",
  "permissionLevel": "READ_WRITE",
  "scopes": [
    "servers:read",    // Lista serwerów
    "servers:power"    // Start/Stop/Restart
  ]
}

Przykład - Backup automation:

json

{
  "name": "Backup Script",
  "permissionLevel": "READ_WRITE",
  "scopes": [
    "servers:read",
    "backups:read",
    "backups:write"
  ]
}

IP Whitelisting

Ogranicz dostęp do klucza tylko z określonych adresów IP.

Konfiguracja

Przy tworzeniu klucza:

json

{
  "name": "Production Key",
  "permissionLevel": "FULL_ACCESS",
  "ipWhitelist": [
    "203.0.113.10",
    "198.51.100.0/24",
    "2001:db8::/32"
  ]
}

Formaty:

Pojedynczy IP: 203.0.113.10
Zakres CIDR: 198.51.100.0/24 (198.51.100.0 - 198.51.100.255)
IPv6: 2001:db8::/32

Zachowanie

Żądanie z dozwolonego IP:

bash

# Request z 203.0.113.10
curl -X GET https://sgshub.eu/api/servers \
  -H "Authorization: Bearer sgshub_sk_live_abc123..."

# Response: 200 OK

Żądanie z niedozwolonego IP:

bash

# Request z 192.0.2.50 (nie na whiteliście)
curl -X GET https://sgshub.eu/api/servers \
  -H "Authorization: Bearer sgshub_sk_live_abc123..."

# Response: 403 Forbidden
{
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "Żądanie z IP 192.0.2.50 jest zablokowane. Dozwolone IP: [203.0.113.10, 198.51.100.0/24]",
    "clientIp": "192.0.2.50"
  }
}

Wykrywanie IP klienta

API sprawdza IP w następującej kolejności:

X-Forwarded-For header (pierwszy IP w łańcuchu)
X-Real-IP header
Socket remote address

Proxy/CDN

Jeśli używasz proxy (Cloudflare, nginx), upewnij się że przekazuje prawdziwy IP klienta w headerze X-Forwarded-For.

Rate Limiting per klucz

Każdy klucz API ma indywidualne limity rate limiting.

Limity domyślne

Plan	Limit/minutę	Limit/dzień
Starter (G)	300	20,000
Advanced (A)	500	40,000
Master (M)	1,000	100,000
Elite (E)	3,000	300,000
Royal (R)	5,000	500,000

Custom limity

Możesz ustawić niższe limity dla konkretnego klucza (bezpieczeństwo):

json

{
  "name": "Public Dashboard Key",
  "permissionLevel": "READ_ONLY",
  "rateLimit": {
    "perMinute": 50,   // Niższy niż domyślny 100
    "perDay": 2000     // Niższy niż domyślny 5000
  }
}

Sprawdzanie limitów

Response headers:

http

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1698336060
X-RateLimit-Key: key_xyz789

Przy przekroczeniu:

http

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1698336060

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Klucz API 'Production Bot' przekroczył limit 100 zapytań/minutę.",
    "keyId": "key_xyz789",
    "keyName": "Production Bot",
    "limit": 100,
    "retryAfter": 45
  }
}

Wygasanie kluczy

Automatyczne wygasanie

Ustaw datę wygaśnięcia przy tworzeniu:

json

{
  "name": "Temporary Key",
  "permissionLevel": "READ_ONLY",
  "expiresAt": "2025-12-31T23:59:59Z"
}

Po wygaśnięciu:

http

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "Klucz API wygasł 2025-12-31T23:59:59Z. Utwórz nowy klucz.",
    "expiredAt": "2025-12-31T23:59:59Z"
  }
}

Przypomnienia

System wysyła emaile:

30 dni przed wygaśnięciem - przypomnienie
7 dni przed wygaśnięciem - ostrzeżenie
1 dzień przed wygaśnięciem - ostatnie ostrzeżenie

Możesz przedłużyć klucz przez Dashboard lub API:

bash

curl -X PATCH https://sgshub.eu/api/wellness/api-keys/key_xyz789 \
  -H "Authorization: Bearer sgshub_sk_live_abc123..." \
  -d '{
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Rotacja kluczy

Dlaczego rotować?

Zalecana częstotliwość:

Produkcja: co 90 dni
Development: co 180 dni
Tymczasowe klucze: po zakończeniu projektu

Powody rotacji:

Compromised key (wyciek)
Odejście członka zespołu
Zmiana uprawnień
Regularne security hygiene

Jak rotować (zero downtime)

Krok 1: Utwórz nowy klucz

bash

# Tworzy nowy klucz z tymi samymi uprawnieniami
curl -X POST https://sgshub.eu/api/wellness/api-keys/key_old123/rotate \
  -H "Authorization: Bearer sgshub_sk_live_old123..."

Response:

json

{
  "data": {
    "oldKey": {
      "id": "key_old123",
      "status": "ROTATING",
      "validUntil": "2025-11-02T15:30:00Z"  // +7 dni
    },
    "newKey": {
      "id": "key_new456",
      "key": "sgshub_sk_live_new456...",
      "permissionLevel": "READ_WRITE",
      "scopes": ["servers:read", "servers:write"],
      "createdAt": "2025-10-26T15:30:00Z"
    }
  }
}

Krok 2: Update aplikacji W ciągu 7 dni zamień stary klucz na nowy:

bash

# .env
-SGSHUB_API_KEY=sgshub_sk_live_old123...
+SGSHUB_API_KEY=sgshub_sk_live_new456...

Krok 3: Revoke stary klucz Po wdrożeniu nowego klucza, unieważnij stary:

bash

curl -X DELETE https://sgshub.eu/api/wellness/api-keys/key_old123 \
  -H "Authorization: Bearer sgshub_sk_live_new456..."

Overlap period

Podczas rotacji oba klucze działają przez 7 dni - możesz bezpiecznie przełączyć się bez przestoju.

Błędy uwierzytelniania

401 Unauthorized

Brak header Authorization:

http

GET /api/servers HTTP/1.1

Response:
{
  "error": {
    "code": "MISSING_AUTHORIZATION",
    "message": "Brak header Authorization. Użyj: Authorization: Bearer YOUR_API_KEY"
  }
}

Nieprawidłowy format:

http

Authorization: sgshub_sk_live_abc123...  (brak "Bearer")

Response:
{
  "error": {
    "code": "INVALID_AUTH_FORMAT",
    "message": "Nieprawidłowy format. Użyj: Authorization: Bearer YOUR_API_KEY"
  }
}

Nieprawidłowy klucz:

http

Authorization: Bearer sgshub_sk_live_WRONG...

Response:
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Klucz API nieprawidłowy lub unieważniony."
  }
}

Wygasły klucz:

http

Authorization: Bearer sgshub_sk_live_expired...

Response:
{
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "Klucz API wygasł 2025-09-30T00:00:00Z.",
    "expiredAt": "2025-09-30T00:00:00Z"
  }
}

403 Forbidden

Brak uprawnień (scope):

http

POST /api/servers
Authorization: Bearer sgshub_sk_live_readonly...

Response:
{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Klucz API nie ma wymaganych uprawnień: servers:write",
    "requiredScopes": ["servers:write"],
    "grantedScopes": ["servers:read"]
  }
}

IP nie na whiteliście:

http

GET /api/servers
Authorization: Bearer sgshub_sk_live_whitelisted...
X-Forwarded-For: 192.0.2.100

Response:
{
  "error": {
    "code": "IP_NOT_WHITELISTED",
    "message": "IP 192.0.2.100 nie jest na whiteliście.",
    "clientIp": "192.0.2.100",
    "allowedIps": ["203.0.113.10", "198.51.100.0/24"]
  }
}

Najlepsze praktyki

1. Używaj zmiennych środowiskowych

❌ Źle:

javascript

const apiKey = 'sgshub_sk_live_abc123...';  // Hardcoded

✅ Dobrze:

javascript

const apiKey = process.env.SGSHUB_API_KEY;

2. Różne klucze dla różnych środowisk

bash

# .env.development
SGSHUB_API_KEY=sgshub_sk_test_dev123...

# .env.production
SGSHUB_API_KEY=sgshub_sk_live_prod456...

3. Principle of Least Privilege

Nadawaj minimalne potrzebne uprawnienia:

❌ Źle:

json

{
  "name": "Read-only Dashboard",
  "permissionLevel": "FULL_ACCESS"  // Za dużo!
}

✅ Dobrze:

json

{
  "name": "Read-only Dashboard",
  "permissionLevel": "READ_ONLY",
  "scopes": ["servers:read", "mods:read"]
}

4. IP Whitelisting dla produkcji

Jeśli statyczny IP dostępny, użyj whitelistingu:

json

{
  "name": "Production Server",
  "ipWhitelist": ["203.0.113.10"]  // Tylko ten IP
}

5. Monitoring użycia

Regularnie sprawdzaj:

Dashboard → Wellness → Monitoring → sekcja "API Keys"
Nieużywane klucze → usuń
Podejrzana aktywność → rotuj

6. Nigdy nie commituj kluczy do Git

Dodaj do .gitignore:

.env
.env.local
.env.production
*.key
secrets/

Jeśli przypadkowo commitujesz:

Natychmiast revoke klucz (Dashboard → Wellness → API Keys)
Utwórz nowy klucz
Usuń klucz z historii Git (git filter-branch lub BFG Repo-Cleaner)
Force push (jeśli publiczne repo)

7. Loguj błędy uwierzytelniania

javascript

axios.interceptors.response.use(
  response => response,
  error => {
    if (error.response?.status === 401) {
      logger.error('API Key invalid or expired', {
        keyId: error.response.data.error.keyId,
        endpoint: error.config.url
      });
      // Notify admin
    }
    throw error;
  }
);

Powiązane strony

Wprowadzenie do API - podstawy SGS Hub API
Wellness: API Keys - zarządzanie kluczami przez Dashboard
Wellness: Monitoring - śledzenie użycia API
Przykłady kodu - kompletne implementacje uwierzytelniania

Uwierzytelnianie ​

Przegląd ​

Tworzenie klucza API ​

Przez Dashboard ​

Przez API ​

Format klucza ​

Poziomy uprawnień ​

Read Only ​

Read + Write ​

Full Access ​

Zakresy (Scopes) ​

Dostępne zakresy ​

Mapowanie poziomów → scopes ​

Custom scopes ​

IP Whitelisting ​

Konfiguracja ​

Zachowanie ​

Wykrywanie IP klienta ​

Rate Limiting per klucz ​

Limity domyślne ​

Custom limity ​

Sprawdzanie limitów ​

Wygasanie kluczy ​

Automatyczne wygasanie ​

Przypomnienia ​

Rotacja kluczy ​

Dlaczego rotować? ​

Jak rotować (zero downtime) ​

Błędy uwierzytelniania ​

401 Unauthorized ​

403 Forbidden ​

Najlepsze praktyki ​

1. Używaj zmiennych środowiskowych ​

2. Różne klucze dla różnych środowisk ​

3. Principle of Least Privilege ​

4. IP Whitelisting dla produkcji ​

5. Monitoring użycia ​

6. Nigdy nie commituj kluczy do Git ​

7. Loguj błędy uwierzytelniania ​

Powiązane strony ​

Uwierzytelnianie

Przegląd

Tworzenie klucza API

Przez Dashboard

Przez API

Format klucza

Poziomy uprawnień

Read Only

Read + Write

Full Access

Zakresy (Scopes)

Dostępne zakresy

Mapowanie poziomów → scopes

Custom scopes

IP Whitelisting

Konfiguracja

Zachowanie

Wykrywanie IP klienta

Rate Limiting per klucz

Limity domyślne

Custom limity

Sprawdzanie limitów

Wygasanie kluczy

Automatyczne wygasanie

Przypomnienia

Rotacja kluczy

Dlaczego rotować?

Jak rotować (zero downtime)

Błędy uwierzytelniania

401 Unauthorized

403 Forbidden

Najlepsze praktyki

1. Używaj zmiennych środowiskowych

2. Różne klucze dla różnych środowisk

3. Principle of Least Privilege

4. IP Whitelisting dla produkcji

5. Monitoring użycia

6. Nigdy nie commituj kluczy do Git

7. Loguj błędy uwierzytelniania

Powiązane strony