Scopes and enablement

Permissions are called scopes. Whether a call succeeds is decided on three levels.

The three levels

1. Enablement of your account. Shirtee decides which scopes your account may use at all: a default for all merchants plus additional rights for individual merchants. Both together are effective. This set can change.
2. Scopes of the key. When you create a key you pick, from the enabled scopes, those the key should carry. The key keeps them until it expires.
3. Requirement of the endpoint. Every operation lists in the spec under x-customer-scopes the scopes it accepts. Your key needs at least one of them.

At call time the intersection of levels 1 and 2 applies, evaluated on every request. If Shirtee removes a scope from the enablement, an already issued key loses it from the next request.

Where to see what is enabled

In the portal under KI-Assistent & API, creating a key offers only enabled permissions. The Fähigkeiten (capabilities) area explains them. If a permission is missing, contact support.

The scopes

Scope	Allows
merchant_order:read	Read your own orders, tracking and history; previews for cancellation, address change and variant swap
merchant_order:create	Create orders, re-order and upload delivery receipts
merchant_order:cancel	Cancel orders
merchant_order:address	Change delivery and billing address
merchant_order:items	Swap variants and add, change or delete items
merchant_order:write	Umbrella scope: all write permissions for orders
merchant_catalog:read	Read product catalog, variants and stock
merchant_invoice:read	Read your own invoices
merchant_complaint:write	Create complaint drafts
warehouse:read	Read inbound shipments and warehouse items
warehouse:shipment_write	Create and change inbound shipments and import shipping lists
warehouse:shipment_cancel	Cancel inbound shipments
warehouse:document_write	Upload and remove documents on inbound shipments
warehouse:write	Umbrella scope: all warehouse write permissions

An operation accepts the fine-grained scope and the matching umbrella scope. Request the fine-grained scopes for new keys so you grant no more than the software needs.

Why does my key return 403?

Work through these steps in order:

1. Read the message. Scoped API key revoked means the key was revoked. Create a new one.
2. Check the operation. Is the endpoint in the reference? A merchant key rejects everything else.
3. Compare scopes. Take the operation’s x-customer-scopes and compare them with your key’s permissions (portal, API keys). If the key carries none of them, you need a new key.
4. Check enablement. If the key carries the scope but it is not (or no longer) enabled for your account, only support can help.