API z kluczem

Utwórz klucz API sklepu, nadaj mu minimalny zakres i wyślij pierwsze żądanie.

Klucz API to sekret dla programu: raportu, bota, własnego panelu albo CLI itemshop deploy. Każdy klucz jest przypisany do jednego sklepu i ma jawną listę uprawnień. Przekazujesz go w nagłówku:

X-API-Key: isk_<64 znaki hex>

Bazowy URL: https://itemshop.dev/api/v2. Dane do strony sklepu (produkty, kasa) pobierasz bez klucza — przez Storefront API. Klucz jest potrzebny dopiero do operacji na danych sklepu.

​

Typy kluczy

Typ	Do czego	Domyślny zakres
shop	Wywołania REST dla jednego sklepu: integracje, raporty, automatyzacje, CLI.	wybrany preset
plugin	Wyłącznie oficjalny protokół realizacji (Socket.IO). Nie używaj go jako zwykłego klucza REST.	orders:write

Kluczy obejmujących całe konto nie ma. Operacje na koncie, utworzenie sklepu, usunięcie sklepu i inne akcje tylko dla właściciela wymagają sesji panelu (Authorization: Bearer).

​

Utworzenie klucza

1. Otwórz klucze API sklepu

   W panelu wybierz sklep i przejdź do Klucze API. Klucze tworzy się tylko w panelu — endpointy zarządzania kluczami (/api-keys) przyjmują wyłącznie sesję.

2. Wybierz preset

   Plugin Minecraft ustawia typ plugin i orders:write. Integracja sklepu proponuje zakres tylko do odczytu. Pełny dostęp (*) wybieraj wyłącznie dla własnego, zaufanego systemu.

3. Nazwij klucz i zawęź zakres

   Nazwa (1–100 znaków) powinna wskazywać usługę i środowisko, np. „Raporty produkcja”. Zaznacz tylko te uprawnienia, których integracja naprawdę używa.

4. Ustaw wygaśnięcie (opcjonalnie)

   Dla integracji tymczasowych ustaw datę. Data w przeszłości jest odrzucana; wygaśnięcie jest sprawdzane przy każdym użyciu.

5. Skopiuj sekret

   Pełny klucz (isk_ + 64 znaki hex) jest pokazywany tylko raz. Backend przechowuje wyłącznie jego skrót SHA-256 — zgubionego sekretu nie da się odzyskać. Zapisz go w menedżerze sekretów, nigdy w repozytorium ani w kodzie strony.

Klucz nie może trafić do przeglądarki. Kod strony sklepu jest publiczny — strona korzysta z Storefront API, które nie wymaga sekretów.

​

Uprawnienia

Uprawnienie ma postać zasób:akcja. Akcje: read, write, delete, manage.

• write zawiera read tego samego zasobu;
• manage zawiera read, write i delete;
• wildcard zasobu (products:*) i globalny * trzeba nadać jawnie;
• stare aliasy read / write / delete (dla wszystkich zasobów) nadal działają; alias admin jest odrzucany.

Zasób	Obejmuje
shop	ustawienia sklepu, branding, VAT, konfiguracja e-mail, domena
products	produkty i ich kolejność
servers	serwery gry
orders	zamówienia, statusy, ręczna realizacja; klucz plugin potrzebuje orders:write
payments	sesje i transakcje płatności
payment-methods	metody płatności sklepu
discounts	kody rabatowe
vouchers	vouchery
stats	statystyki i raporty
api-keys	zarządzanie kluczami API
team	członkowie zespołu i ich uprawnienia
site	Od 3.0. site:read — odczyt plików, rewizji i buildów strony; site:write — zapis plików, upload, build i publikacja (używa go itemshop deploy).
catalog	Od 3.0. catalog:read / catalog:write — katalog produktów w narzędziach MCP (tokeny workspace).

Aktualny katalog (z opisami PL/EN) zwraca publiczny endpoint GET /api-keys/permissions.

Członek zespołu może utworzyć lub rozszerzyć klucz tylko do zakresu, który sam posiada — nie może też nadać *. Gdy autor klucza straci dostęp do sklepu albo prawo zarządzania kluczami, jego klucz przestaje działać.

​

Przypisanie do sklepu

Klucz działa tylko dla shopId, do którego go utworzono. Każde żądanie z shopId w ścieżce jest porównywane z kluczem, a identyfikator zasobu (produktu, serwera, zamówienia) musi należeć do tego samego sklepu.

Sytuacja	Odpowiedź
nieprawidłowy format shopId (nie 24 znaki hex)	400
brak, błędny, wygasły lub odwołany klucz	401
poprawny klucz, ale za mały zakres albo inny sklep	403
sklep lub zasób nie istnieje w tym sklepie	404

Klucz działa tylko na endpointach oznaczonych w API reference jako apiKeyAuth. Podanie klucza nie zamienia go w sesję — trasy tylko dla właściciela i zwykłe trasy Bearer go odrzucają. Jeśli endpoint akceptuje oba mechanizmy i żądanie zawiera oba, sprawdzany jest klucz.

​

Pierwsze żądanie

Pobierz listę produktów sklepu (wymaga products:read):

curl

curl https://itemshop.dev/api/v2/products/<shopId> \
  -H "X-API-Key: $ITEMSHOP_API_KEY"

Odpowiedź ma stały kształt:

{
  "success": true,
  "data": [
    { "_id": "664f1a2b3c4d5e6f7a8b9c0d", "name": "VIP 30 dni", "slug": "vip-30-dni", "price": 19.99, "isActive": true }
  ]
}

Inne przydatne pierwsze wywołania: GET /shops/<shopId> (dane sklepu, shop:read), GET /orders/<shopId>?status=paid&page=1&limit=20 (zamówienia, orders:read), GET /stats/<shopId>/dashboard (statystyki, stats:read).

SDK TypeScript i Python pojawiają się razem z ItemShop 3.0. Do tego czasu używaj czystego HTTP — każde żądanie z karty curl działa tak samo z dowolnego języka.

​

Tokeny workspace

Od ItemShop 3.0. Kształt opisany według kontraktu — szczegóły mogą się jeszcze zmienić.

Token workspace to klucz API przeznaczony dla agentów AI (Claude Code, Codex, Cursor i inni) łączących się z hostowanym serwerem MCP pod adresem https://itemshop.dev/api/v2/mcp.

• Tworzysz go w panelu: Workspace → MCP, nadając nazwę i zakresy.
• Pełny token jest pokazywany tylko raz; na liście widać ostatnie użycie, a każdy token możesz w dowolnej chwili unieważnić.
• Dostępne zakresy: site:read, site:write, catalog:read, catalog:write, orders:read, discounts:write, stats:read.
• Agent przekazuje go jako Authorization: Bearer <token> (nie w X-API-Key).

claude mcp add --transport http itemshop https://itemshop.dev/api/v2/mcp \
  --header "Authorization: Bearer $ITEMSHOP_WORKSPACE_TOKEN"

Ani klucz API, ani token workspace nie może wyjść poza uprawnienia osoby, która go utworzyła — zakres jest zawsze podzbiorem jej roli w sklepie.

​

Rotacja i odwołanie

Na liście kluczy widać nazwę, typ, skrócony podgląd, zakres, datę utworzenia, ostatnie użycie, wygaśnięcie i status. Możesz zmienić nazwę albo zmniejszyć zakres istniejącego klucza.

Rotacja (bez przestoju):

1. Utwórz nowy klucz

   Z tym samym zakresem i nową nazwą, np. „Raporty produkcja 2026-11”.

2. Podmień sekret w usłudze

   Wdróż nowy klucz i sprawdź w panelu, że ma świeże „ostatnie użycie”.

3. Odwołaj stary klucz

   Odwołanie działa natychmiast (cache kluczy jest unieważniany).

Odwołaj klucz od razu, gdy:

• trafił do logów, czatu, zgłoszenia albo publicznego repozytorium;
• usługa, która go używała, została wyłączona;
• nie rozpoznajesz ostatniego użycia;
• zmienił się właściciel integracji albo serwera.

Utworzenie klucza jest limitowane do 10 na minutę — zobacz Błędy i limity.

​

Dalej

Błędy i limity

Kształt błędów, kody, limity żądań i bezpieczne ponawianie.

API reference

Wszystkie endpointy z interaktywnym „Wypróbuj”.

SDK TypeScript

createClient, createStorefront i CLI itemshop.

Protokół pluginu

Jak klucz typu plugin łączy serwer gry z ItemShop.