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

# Authentication

> Dashboard sessions, shop keys, and plugin keys in ItemShop v2.

ItemShop separates human authentication from machine access. Each endpoint states the accepted mechanism in OpenAPI.

## Dashboard session

Email/OAuth sign-in creates a user session and the backend receives a Bearer token. A session is required for account operations, shop creation, and owner-only actions.

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

Do not embed dashboard tokens in server-side scripts. Use a key bound to the shop instead.

## Shop integration key

Create a `shop` key inside the relevant store dashboard and send it in every request:

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

The key works only for its bound `shopId` and only on endpoints marked `apiKeyAuth` in OpenAPI. It needs an explicit `resource:action` permission such as `products:read`, `orders:write`, or `stats:read`.

`write` includes `read` on the same resource, while `manage` includes `read`, `write`, and `delete`. Resource wildcards (`products:*`) and the global `*` are explicit. The old `admin` alias is rejected.

<Warning>
  A key never becomes a user session. Owner-only and ordinary Bearer routes reject it. A key also cannot access another shop, even if the caller knows that shop's identifier.
</Warning>

## Plugin key

A `plugin` key is reserved for the official real-time fulfillment protocol. By default it receives only `orders:write`, is bound to one shop, and the connection also identifies a server owned by that shop. Do not use it as a general REST key.

## Key lifecycle

* the full secret is shown once;
* the backend stores only a hash;
* an optional expiry is checked on every use;
* losing shop access or API-key-management rights invalidates a shop-bound key created by that member;
* a team member cannot mint a key broader than their own permissions;
* revocation invalidates the key and its cache entry.

## Public endpoints

Some routes need no authentication, including public shop catalogs, controlled checkout, voucher redemption, and payment-provider webhooks. Public does not mean unrestricted: input validation and rate limits apply, while checkout also requires legal consents, the shown-document version, an idempotency key, and Turnstile protection.