API · Keys and scopesDocs navigation

API keys and scopes

A shop holds up to 10 keys. The full key is shown once: Shoplio stores only a hash of it.

On this page

Create a key

  1. Open Developer in the dashboard, with the shop selected.
  2. Name the key and tick its scopes.
  3. Copy the key when it is shown. It is not shown again.
  • Only the shop owner can create, change or delete keys.
  • A key belongs to one shop. It can never reach another shop's data.

Send the key

Header
Authorization: Bearer shp_0123456789abcdef0123456789abcdef

A key is shp_ followed by 32 hexadecimal characters. The dashboard later shows only its first 12 characters.

Scopes

Each endpoint needs one scope. A call without it answers 403 and names the scope, for example API key lacks the read_stock permission.

ScopeAllowsOn a new key
read_productsShop profile and product catalogueOn
write_productsCreate and update products and variants (no deletes)On
read_stockList unsold stock, decryptedOn
write_stockPush new stock itemsOn
edit_stockReplace the content of an unsold itemOff
delete_stockRemove unsold items, singly or in bulkOff
read_ordersOrders (including decrypted delivered content) and customer accountsOn
write_ordersCredit or debit store creditOn
fulfill_ordersDeliver paid, pre-ordered or out-of-stock orders from your stockOff
read_analyticsYour crypto balance per gatewayOn

A new key gets seven scopes unless you change them. edit_stock, delete_stock and fulfill_orders stay off until you tick them.

Regenerate, edit or delete a key

  • Regenerating a key issues a new secret. The old one stops working at once.
  • Editing scopes changes what the key may do and keeps the secret.
  • Deleting a key removes it for good.

When a key is refused

Every authentication failure answers the same 401. The API never says which cause it was.

401 Unauthorized
{ "success": false, "error": "Invalid or missing API key" }
  • The Authorization header is missing, or is not Bearer shp_....
  • No key matches: it was mistyped, deleted or regenerated.
  • The shop is inactive.
  • The owner's account is suspended.
  • The owner is no longer on Pro or Enterprise.

If the docs do not cover it, ask on Telegram or use the contact form.