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

# Uwierzytelnianie

> Sesja panelu, klucze sklepu i klucze pluginu w ItemShop v2.

ItemShop rozdziela uwierzytelnianie człowieka od dostępu maszynowego. Endpoint zawsze wskazuje w OpenAPI, który mechanizm akceptuje.

## Sesja panelu

Logowanie e-mailem/OAuth tworzy sesję użytkownika, a backend otrzymuje token Bearer. Sesja jest wymagana m.in. dla operacji na koncie, utworzenia sklepu oraz operacji zastrzeżonych wyłącznie dla właściciela.

```http theme={null}
Authorization: Bearer <access-token>
```

Tokenów panelu nie umieszczaj w skryptach serwerowych. Do integracji użyj klucza przypisanego do sklepu.

## Klucz integracji sklepu

Klucz typu `shop` tworzysz w panelu danego sklepu. Każde żądanie przekazuje go w nagłówku:

```http theme={null}
X-API-Key: <klucz>
```

Klucz działa tylko dla `shopId`, do którego został przypisany, i tylko na endpointach oznaczonych w OpenAPI jako `apiKeyAuth`. Wymagane jest konkretne uprawnienie `resource:action`, np. `products:read`, `orders:write` albo `stats:read`.

`write` zawiera `read` tego samego zasobu, a `manage` zawiera `read`, `write` i `delete`. Wildcard zasobu (`products:*`) oraz globalny `*` są jawne. Alias `admin` jest odrzucany.

<Warning>
  Podanie klucza nie zmienia go w sesję użytkownika. Endpointy tylko dla właściciela i zwykłe trasy Bearer odrzucają klucz. Klucz nie może też odczytać innego sklepu, nawet gdy zna jego identyfikator.
</Warning>

## Klucz pluginu

Klucz typu `plugin` służy wyłącznie oficjalnemu protokołowi realizacji w czasie rzeczywistym. Domyślnie otrzymuje tylko `orders:write`, jest związany ze sklepem, a połączenie dodatkowo wskazuje serwer należący do tego sklepu. Nie używaj go jako ogólnego klucza REST.

## Cykl życia klucza

* pełny sekret jest pokazywany tylko raz;
* backend przechowuje wyłącznie skrót klucza;
* opcjonalna data wygaśnięcia jest sprawdzana przy każdym użyciu;
* utrata dostępu autora do sklepu albo prawa do zarządzania kluczami unieważnia klucz powiązany ze sklepem;
* członek zespołu nie może utworzyć klucza z szerszym zakresem niż własne uprawnienia;
* odwołanie klucza działa natychmiast po unieważnieniu cache.

## Endpointy publiczne

Niektóre trasy nie wymagają uwierzytelnienia, np. publiczny katalog sklepu, kontrolowany checkout, realizacja vouchera i webhooki operatorów płatności. Publiczny nie znaczy nieograniczony — obowiązują walidacja danych, limity żądań, a w checkout także zgody prawne, wersja dokumentów, idempotency key i ochrona Turnstile.