Scopes
Scopes define the maximum a key can do. The acting user's current ShelfCycle permissions can only narrow that access.
Keys are issued to a ShelfCycle user for attribution and live permission checks. A key must have the endpoint scope, and the acting user must still have the required ShelfCycle permission. GET /me returns both the raw scopes and effective capabilities after live RBAC.
Scope list
| Scope | Endpoints |
|---|---|
search:read | GET /search, legacy safe detail readback for customers, suppliers, contacts, and products, and exact parent-scoped child or document reads after selecting a visible parent. |
notes:read | GET /notes, GET /notes/{id} |
notes:write | POST /notes, PATCH /notes/{id}, and API-created note readback. |
contacts:read | GET /contacts, GET /contacts/{id} |
contacts:create | POST /contacts |
contacts:update | GET /contacts/{id}, PATCH /contacts/{id} |
customers:read | GET /customers, GET /customers/{id}, and GET /customers/{id}/documents |
customers:write | POST /customers, PATCH /customers/{id}, parent-scoped customer location/address writes, and POST /customers/{id}/documents. |
suppliers:read | GET /suppliers, GET /suppliers/{id}, and GET /suppliers/{id}/documents |
suppliers:write | POST /suppliers, PATCH /suppliers/{id}, parent-scoped supplier ship-from writes, and POST /suppliers/{id}/documents. |
products:read | GET /products, GET /products/{id}, GET /products/{id}/documents, and product setup reference lookups. |
products:write | POST /products, PATCH /products/{id}, POST /product-families, PATCH /product-families/{id}, and POST /products/{id}/documents. |
orders:read | GET /orders, GET /orders/{id} |
purchase-orders:read | GET /purchase-orders, GET /purchase-orders/{id} |
commercial-economics:read | Profit, margin, cost basis, cost rows, and totals explanations on scoped sales-order and purchase-order detail reads. |
company-reference:read | GET /reference/customers and GET /reference/suppliers active matching directories. |
reports:read | GET /reports and GET /reports/{reportKey} governed commercial report rollups. |
Scope ceiling
A key with only search:read cannot write anything. A key with company-reference:read can page active customer and supplier matching hints, but it cannot read contacts, order history, prices, costs, margin, payment, tax, ledger, or raw address details. A key with orders:read can read sales-order documents, but it cannot mutate orders, invoices, allocations, costs, shipments, or GL. A key with commercial-economics:read can read permitted profit, margin, and cost details only when it is paired with the relevant order read scope and the acting user still has live permission. A key with reports:read can discover and run governed report rollups that the acting user can access, but it cannot request row-level exports, schedule reports, create files, recalculate costs, or mutate records. A key with customers:write can create or patch bounded public customer profile, location, address, and attached document link fields, but it cannot change credit, accounting, workflow, tax, representative settings, archive state, primary-location assignment, upload files, or delete documents. A key with products:write can create and update bounded product records and product families, and it can attach product document links, but it cannot create packaging, suppliers, product code attributes, catalog attributes, inventory, prices, costs, orders, binary uploads, document deletion, or accounting records.
Restricted and full access keys
Most keys are restricted to named scopes. Full access keys can carry the current public API scope set, but they are still tenant-bound, user-attributed, revocable, and narrowed by live ShelfCycle permissions.
GET /me reports:
| Field | Use it for |
|---|---|
key.accessMode | Whether the key is restricted or full. |
key.storedGrants | The grants stored on the key, which may be named scopes or a broad public API grant. |
key.effectiveScopes | The current scope list a caller should reason over after expanding broad grants and removing retired scopes. |
key.retiredScopes | Any stored grants that no longer map to current public API scopes. |
Use effectiveScopes, not storedGrants, when deciding which endpoint families a workflow may call.
Live user permission floor
Scopes are not the only authorization check. The API also checks the acting user's current ShelfCycle permissions. If that user is removed, inactive, or loses the required role, the key loses that ability without changing the key.
Do not treat scopes as a substitute for user permissions. The API requires both.
Effective capabilities
Use GET /me to inspect what the key can actually do now. The response includes capability groups for search, notes, contacts, customers, suppliers, company reference, products, product families, orders, purchase orders, reports, and write readiness. Customer capabilities include nested location, address, and document access. Supplier capabilities include nested ship-from and document access. Product capabilities report view, create, update, and document access. Product-family capabilities report view, create, and update access. Company-reference capabilities report whether active directory paging is available for customers and suppliers. Order and purchase-order capabilities report whether changed-record discovery and profit, margin, and cost details are available. Report capabilities list the report keys available to the current key and actor. Write-readiness capabilities report whether dryRun checks are available for supported notes, contacts, customers, suppliers, child records, products, product families, and attached documents. A scope can be present while the corresponding effective capability is false because the acting user lacks live permission.
Repair metadata does not introduce a new scope. v1.20 may add repairCategory, suggestedAction, validValues, accepted filters, examples, and retry guidance to errors for the scopes a key already uses.
Write readiness and scopes
dryRun=true does not introduce a separate scope. It uses the same write scope, live user permission, and rate-limit family as execution:
| Write family | Readiness scope |
|---|---|
POST /notes, PATCH /notes/{id} | notes:write |
POST /contacts | contacts:create |
PATCH /contacts/{id} | contacts:update |
POST /customers, PATCH /customers/{id} | customers:write |
POST /suppliers, PATCH /suppliers/{id} | suppliers:write |
POST /customers/{id}/locations, PATCH /customers/{id}/locations/{locationId}, and customer address writes | customers:write |
POST /customers/{id}/documents | customers:write |
POST /suppliers/{id}/ship-from-locations, PATCH /suppliers/{id}/ship-from-locations/{locationId} | suppliers:write |
POST /suppliers/{id}/documents | suppliers:write |
POST /products, PATCH /products/{id}, POST /product-families, PATCH /product-families/{id} | products:write |
POST /products/{id}/documents | products:write |
Authorized callers may execute without dryRun when their integration policy allows it. ShelfCycle does not require human approval before these supported public API writes.
Missing access
The two access errors are distinct.
{
"error": {
"type": "permission_error",
"code": "missing_scope",
"message": "The API key does not include the required scope.",
"requestId": "request-id"
}
}
{
"error": {
"type": "permission_error",
"code": "missing_permission",
"message": "The acting user does not have permission for this operation.",
"requestId": "request-id"
}
}