Scopes
The access each scope grants and which endpoints a key can reach.
Scopes control what an API key can do. Each endpoint requires exactly one scope, and a key reaches only the endpoints whose scope it holds. The store owner picks the scopes when creating or editing a key, so grant a key only the scopes its integration needs.
Available scopes
| Scope | Grants |
|---|---|
store:read | Read store details (GET /v1/store) and loyalty tiers (GET /v1/loyalty/tiers). |
products:read | Read products. |
products:write | Create and update products. |
products:deliver | Deliver a product to a resident. |
customers:read | Read customers, including their spend. |
customers:write | Update customers, and ban or unban them. |
credits:read | Read a customer's store credit. |
credits:write | Set or adjust a customer's store credit. |
categories:read | Read categories. |
categories:write | Create, update, and delete categories, and manage their products. |
coupons:read | Read coupons. |
coupons:write | Create and update coupons. |
coupons:apply | Apply a coupon to, or revoke one from, a customer. |
giftcards:read | Read gift cards. |
giftcards:write | Grant, update, and disable gift cards. |
How scopes map to endpoints
A request that authenticates with a valid key but lacks the endpoint's scope returns 403. The scope each endpoint requires is listed on that endpoint's reference page. Read and write are separate scopes within most areas, so a read-only integration never needs a write scope.
One pairing is worth noting: a single scope can gate endpoints in more than one area. store:read covers both the store details endpoint and the loyalty tiers endpoint, because loyalty tiers are part of the store's read surface.