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

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

> [!WARNING]
>
> A key must never reach the browser. Your shop's website code is public — it uses the [Storefront API](https://andcze.mintlify.site/en/developers/storefront-api.md), 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.

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

```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 — available from 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}
# itemshop package — available from 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)
```

The response always has the same shape:

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

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

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

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

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

## Next

> **[Errors and limits](https://andcze.mintlify.site/en/developers/errors-and-limits.md)**
>
> Error shape, codes, rate limits and safe retries.

> **[API reference](https://andcze.mintlify.site/en/api-reference/overview.md)**
>
> Every endpoint with an interactive "Try it".

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

> **[Plugin protocol](https://andcze.mintlify.site/en/developers/plugin-protocol.md)**
>
> How a `plugin` key connects a game server to ItemShop.


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