Skip to content

Scopes

What each scope of an API key unlocks, and how read and write scopes relate.

Version v1.1, updated

On this page

A scope is one thing an API key may do, such as reading products. The company administrator chooses the scopes when creating the key, and each operation needs at most one of them.

The scopes

Scope

Kind

Operations it unlocks

categories:read

Read

GET /v1/categories, GET /v1/categories/{id}

customers:read

Read

GET /v1/customers, GET /v1/customers/{id}

invoices:read

Read

GET /v1/invoices, GET /v1/invoices/{id}, GET /v1/tax-codes

orders:read

Read

GET /v1/orders, GET /v1/orders/{id}

products:read

Read

GET /v1/products, GET /v1/products/{id}

stock:read

Read

GET /v1/stock/levels, GET /v1/warehouses

categories:write

Write

POST /v1/categories, PATCH /v1/categories/{id}, PUT /v1/{resource}/{id}/external-refs/{source}, DELETE /v1/{resource}/{id}/external-refs/{source}

customers:write

Write

POST /v1/customers, POST /v1/customers/batch, PUT /v1/customers/external/{source}/{external_id}, PATCH /v1/customers/{id}, PUT /v1/{resource}/{id}/external-refs/{source}, DELETE /v1/{resource}/{id}/external-refs/{source}

invoices:write

Write

POST /v1/invoices, PATCH /v1/invoices/{id}, POST /v1/invoices/{id}/issue, POST /v1/invoices/{id}/payments, PUT /v1/{resource}/{id}/external-refs/{source}, DELETE /v1/{resource}/{id}/external-refs/{source}

orders:write

Write

POST /v1/orders, PATCH /v1/orders/{id}, POST /v1/orders/{id}/cancel, POST /v1/orders/{id}/confirm, PUT /v1/{resource}/{id}/external-refs/{source}, DELETE /v1/{resource}/{id}/external-refs/{source}

products:write

Write

POST /v1/products, POST /v1/products/batch, PUT /v1/products/external/{source}/{external_id}, PATCH /v1/products/{id}, PUT /v1/{resource}/{id}/external-refs/{source}, DELETE /v1/{resource}/{id}/external-refs/{source}

stock:write

Write

POST /v1/stock/adjustments, PUT /v1/{resource}/{id}/external-refs/{source}, DELETE /v1/{resource}/{id}/external-refs/{source}

GET /v1/me needs no scope, and GET /v1/openapi.json needs no key at all.

Read and write are separate

A write scope does not include the read scope of the same resource, nor the reverse. A system that creates orders and reads them back needs both orders:write and orders:read.

The external ids of a record use the write scope of its resource; warehouses use stock:write. An order that creates its customer on the fly also needs customers:write.

A missing scope

A call without the scope of its operation answers 403 insufficient_scope, with required_scopes. Scopes cannot be added to a key: create a new key with the scopes you need, then revoke the old one.

Related

  • first-key
  • keep-your-key-safe
  • insufficient-scope