API with a key

Create a shop API key, give it the smallest scope it needs and send your first request.

An API key is a secret for a program: a report, a bot, your own dashboard or the itemshop deploy CLI. Every key is bound to one shop and carries an explicit list of permissions. Send it in a header:

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

Base URL: https://itemshop.dev/api/v2. Data for your shop’s website (products, checkout) needs no key — use the Storefront API. A key is only needed to work with your shop’s data.

Key types

Type	Used for	Default scope
shop	REST calls for one shop: integrations, reports, automations, CLI.	chosen preset
plugin	Only the official fulfillment protocol (Socket.IO). Don’t use it as a general REST key.	orders:write

There are no account-wide keys. Account operations, creating or deleting a shop and other owner-only actions require a panel session (Authorization: Bearer).

Create a key

1. Open the shop's API keys

   In the panel pick the shop and go to API keys. Keys are created in the panel only — the key-management endpoints (/api-keys) accept a session, not a key.

2. Pick a preset

   Minecraft plugin sets type plugin and orders:write. Shop integration suggests a read-only scope. Choose Full access (*) only for your own trusted system.

3. Name the key and narrow the scope

   The name (1–100 characters) should identify the service and environment, e.g. “Reports production”. Tick only the permissions the integration actually uses.

4. Set an expiry (optional)

   Set a date for temporary integrations. A date in the past is rejected; expiry is checked on every use.

5. Copy the secret

   The full key (isk_ + 64 hex chars) is shown only once. The backend stores only its SHA-256 hash — a lost secret cannot be recovered. Keep it in a secrets manager, never in a repository or in website code.

A key must never reach the browser. Your shop’s website code is public — it uses the Storefront API, which needs no secrets.

Permissions

A permission has the form resource:action. Actions: read, write, delete, manage.

• write includes read on the same resource;
• manage includes read, write and delete;
• the resource wildcard (products:*) and the global * must be granted explicitly;
• the legacy aliases read / write / delete (all resources) still work; the admin alias is rejected.

Resource	Covers
shop	shop settings, branding, VAT, email configuration, domain
products	products and their order
servers	game servers
orders	orders, statuses, manual fulfillment; a plugin key needs orders:write
payments	payment sessions and transactions
payment-methods	the shop’s payment methods
discounts	discount codes
vouchers	vouchers
stats	statistics and reports
api-keys	API key management
team	team members and their permissions
site	From 3.0. site:read — read site files, revisions and builds; site:write — write files, upload, build and publish (used by itemshop deploy).
catalog	From 3.0. catalog:read / catalog:write — the product catalog in MCP tools (workspace tokens).

The public endpoint GET /api-keys/permissions returns the current catalog with PL/EN descriptions.

A team member can create or widen a key only up to the scope they hold themselves — and cannot grant *. When the key’s creator loses access to the shop or the right to manage keys, their key stops working.

Shop binding

A key works only for the shopId it was created for. Every request with a shopId in the path is checked against the key, and the resource id (product, server, order) must belong to the same shop.

Situation	Response
invalid shopId format (not 24 hex chars)	400
missing, wrong, expired or revoked key	401
valid key but scope too small or a different shop	403
shop or resource doesn’t exist in this shop	404

A key works only on endpoints marked apiKeyAuth in the API reference. Sending a key doesn’t turn it into a session — owner-only routes and plain Bearer routes reject it. If an endpoint accepts both mechanisms and the request carries both, the key is checked.

First request

List the shop’s products (requires products:read):

curl

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

The response always has the same shape:

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

Other useful first calls: GET /shops/<shopId> (shop data, shop:read), GET /orders/<shopId>?status=paid&page=1&limit=20 (orders, orders:read), GET /stats/<shopId>/dashboard (stats, stats:read).

The TypeScript and Python SDKs ship with ItemShop 3.0. Until then use plain HTTP — every request in the curl tab works the same from any language.

Workspace tokens

From ItemShop 3.0. Described according to the contract — details may still change.

A workspace token is an API key meant for AI agents (Claude Code, Codex, Cursor and others) that connect to the hosted MCP server at https://itemshop.dev/api/v2/mcp.

• Create it in the panel: Workspace → MCP, with a name and scopes.
• The full token is shown only once; the list shows last use, and you can revoke any token at any time.
• Available scopes: site:read, site:write, catalog:read, catalog:write, orders:read, discounts:write, stats:read.
• The agent sends it as Authorization: Bearer <token> (not in X-API-Key).

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

Neither an API key nor a workspace token can go beyond the permissions of the person who created it — its scope is always a subset of their role in the shop.

Rotation and revocation

The key list shows the name, type, a short preview, scope, creation date, last use, expiry and status. You can rename an existing key or reduce its scope.

Rotating without downtime:

1. Create a new key

   Same scope, new name, e.g. “Reports production 2026-11”.

2. Swap the secret in your service

   Deploy the new key and check in the panel that it shows a fresh “last used”.

3. Revoke the old key

   Revocation is immediate (the key cache is invalidated).

Revoke a key immediately when:

• it ended up in logs, a chat, a ticket or a public repository;
• the service using it was shut down;
• you don’t recognise its last use;
• the owner of the integration or server changed.

Creating keys is limited to 10 per minute — see Errors and limits.

Next

Errors and limits

Error shape, codes, rate limits and safe retries.

API reference

Every endpoint with an interactive “Try it”.

TypeScript SDK

createClient, createStorefront and the itemshop CLI.

Plugin protocol

How a plugin key connects a game server to ItemShop.