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. |
cost-book-entries:read | GET /cost-book-entries and GET /products/{id}/cost-context. |
cost-book-entries:write | POST /cost-book-entries for readiness checks and verified direct or constructed Cost Book updates. |
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. A key with orders:read can read sales-order documents. A key with commercial-economics:read can read permitted profit, margin, and cost details 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. A key with cost-book-entries:read can read current Cost Book entries, exact product and supplier history, and product cost context. A key with cost-book-entries:write can create or supersede a verified Cost Book entry after the acting user's current access is checked. A key with customers:write can create or patch bounded public customer profile, location, address, and attached document link fields. A key with products:write can create and update bounded product records and product families, and it can attach product document links.
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, Cost Book entries, 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. Cost Book capabilities report whether entries can be viewed or created. 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, attached documents, and Cost Book entries. 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.21 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 |
POST /cost-book-entries | cost-book-entries: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"
}
}