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