Skip to main content
When you create a key, you decide what it can do. On every request we check two things:
  • Is the workspace on a plan that includes the API? If not, you get 403 plan_required.
  • Is this key allowed to do what you’re asking? If not, you get 403 insufficient_scope.

​
How permissions work

A permission is just a resource paired with an action — like “read products” or “create orders.” You can give a key full access, or pick exactly what it’s allowed to touch. The resources you’ll use with the API are:
  • product — products, plus their categories and tags, collections and bundles (they’re all product merchandising)
  • sale — orders
  • sale_payment — recording a payment against an order
  • customer — customers
  • webhook — managing your webhook endpoints
A bulk import is checked per batch: the key needs create and update access on every resource the files you declare will write (products, orders, customers and so on). The action comes from the HTTP method you use: GET reads, POST creates, PUT and PATCH update, and DELETE deletes. So reading a product needs read access to products, creating an order needs create access to orders, and so on.

​
An example

Say you give a key read access to products and orders. It can call GET /v1/products and GET /v1/orders without a problem. But if it tries POST /v1/products, it gets back 403 insufficient_scope — it was never allowed to create products. A full-access key skips these checks and can do everything.

​
Choosing the right permissions

Give a key only what it needs. A dashboard that just shows your sales needs read access and nothing else. An integration that pushes orders in needs to create and read orders. You can change a key’s permissions any time from the dashboard — no need to create a new one.