> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```http theme={null}
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](https://andcze.mintlify.site/pl/developers/storefront-api.md). 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.

> [!WARNING]
>
> Klucz nie może trafić do przeglądarki. Kod strony sklepu jest publiczny — strona korzysta z [Storefront API](https://andcze.mintlify.site/pl/developers/storefront-api.md), 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`.

> [!WARNING]
>
> 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](https://andcze.mintlify.site/pl/api-reference/overview.md) 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`):

```bash curl theme={null}
curl https://itemshop.dev/api/v2/products/<shopId> \
  -H "X-API-Key: $ITEMSHOP_API_KEY"
```

```ts TypeScript theme={null}
// @itemshop/sdk — dostępne od ItemShop 3.0
import { createClient } from "@itemshop/sdk";

const api = createClient({ apiKey: process.env.ITEMSHOP_API_KEY! });
const products = await api.products.list("<shopId>");
console.log(products);
```

```python Python theme={null}
# pakiet itemshop — dostępny od ItemShop 3.0
import os
from itemshop import create_client

api = create_client(api_key=os.environ["ITEMSHOP_API_KEY"])
products = api.products.list("<shopId>")
print(products)
```

Odpowiedź ma stały kształt:

```json theme={null}
{
  "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`).

> [!NOTE]
>
> 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

> [!NOTE]
>
> 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](https://andcze.mintlify.site/pl/developers/mcp.md) 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`).

```bash theme={null}
claude mcp add --transport http itemshop https://itemshop.dev/api/v2/mcp \
  --header "Authorization: Bearer $ITEMSHOP_WORKSPACE_TOKEN"
```

> [!WARNING]
>
> 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](https://andcze.mintlify.site/pl/developers/errors-and-limits.md).

## Dalej

> **[Błędy i limity](https://andcze.mintlify.site/pl/developers/errors-and-limits.md)**
>
> Kształt błędów, kody, limity żądań i bezpieczne ponawianie.

> **[API reference](https://andcze.mintlify.site/pl/api-reference/overview.md)**
>
> Wszystkie endpointy z interaktywnym „Wypróbuj”.

> **[SDK TypeScript](https://andcze.mintlify.site/pl/developers/sdk/typescript.md)**
>
> `createClient`, `createStorefront` i CLI `itemshop`.

> **[Protokół pluginu](https://andcze.mintlify.site/pl/developers/plugin-protocol.md)**
>
> Jak klucz typu `plugin` łączy serwer gry z ItemShop.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.