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
`documents:upload`	`POST /document-uploads` for one private Product, Customer, Supplier, or Purchase Order file upload.
`search:read`	`GET /search`, `GET /entity-resolution`, detail readback for customers, suppliers, contacts, and products, and exact parent-scoped child or document reads after selecting a visible parent.
`tags:read`	`GET /tags`, `GET /tagged-records`, and related tags on Entity Resolution when the acting user has matching Tags and record access.
`notes:read`	`GET /notes`, `GET /notes/{id}`, and organization-wide counts or excerpt lists from `GET /note-activity`.
`notes:write`	`POST /notes`, `PATCH /notes/{id}`, and API-created note readback.
`opportunities:read`	`GET /opportunities` and `GET /opportunities/{id}` for visible customer- and supplier-side opportunities.
`opportunities:write`	`POST /opportunities`, `PATCH /opportunities/{id}`, `POST /opportunities/{id}/close`, `PUT /opportunities/{id}/meta`, and write-compatible detail 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`, `GET /product-directory`, and product setup reference lookups.
`products:write`	`POST /products`, `PATCH /products/{id}`, `POST /product-families`, `PATCH /product-families/{id}`, `POST /products/{id}/documents`, and `PUT /products/{id}/sds`.
`orders:read`	`GET /orders`, `GET /orders/{id}`
`purchase-orders:read`	`GET /purchase-orders`, `GET /purchase-orders/{id}`
`purchase-order-execution:read`	`GET /purchase-order-execution`, `GET /purchase-order-lines/{id}/receipt-events`, and `GET /purchase-orders/{id}/documents`
`inventory:read`	`GET /inventory-balances` for current physical product-by-warehouse balances, availability states, and stock-out counts.
`reorder:read`	`GET /reorder-status` for configured reorder points, allocated and committed demand, projected availability, projected deficit, and status counts.
`certifications:read`	`GET /certification-types`, `GET /certification-records`, exact certification record detail, and `GET /certification-subjects`.
`purchase-order-documents:write`	`POST /purchase-orders/{id}/documents` for readiness checks and verified document association.
`company-reference:read`	`GET /reference/customers` and `GET /reference/suppliers` active matching directories.
`reports:read`	`GET /reports` and `GET /reports/{reportKey}` for sales, purchasing, open-order, pipeline, receivables aging, customer settlement behavior, credit exposure, and invoice charge reports.
`cost-book-entries:read`	`GET /cost-book-entries` by supplier and optional ship-from origin, plus `GET /products/{id}/cost-context`.
`cost-book-entries:write`	`POST /cost-book-entries` for readiness checks and verified direct or constructed Cost Book updates.
`current-cost-sources:read`	`GET /products/{id}/current-cost-source` for a product's supplier-and-origin source state, eligible choices, and selection details.
`current-cost-sources:write`	`PUT /products/{id}/current-cost-source` to preview, set, replace, or clear an exact supplier-location Current Source.
`price-book-entries:read`	`GET /price-book-entries` for active, scheduled, expired, all, and historical configured sale prices.
`price-book-entries:write`	`POST /price-book-entries` for reviewed single-price updates in the organization's base currency.

Scope ceiling

A key with only search:read cannot write anything. A key with tags:read can browse the organization tag vocabulary, find authorized records carrying one exact tag, and receive related tags on Entity Resolution when live access allows it. A key with documents:upload can prepare a private file upload, while the matching record write scope controls whether that file can be attached. A key with notes:read can read notes for a selected visible customer, supplier, or product and can count or review organization-wide note activity when the acting user has current Note viewing access. A key with opportunities:read can find and read visible customer- and supplier-side opportunities. A key with opportunities:write can create, update, close, and maintain details for visible opportunities. A key with company-reference:read can page active customer and supplier matching hints. A key with products:read can find products and product families by regulatory identity or name. A key with orders:read can find sales orders and read their lines, fulfillment context, and totals. A key with purchase-orders:read can find purchase orders and read their lines, receipt summaries, supplier document costs, and totals. A key with purchase-order-execution:read can review current open purchase lines, exact receipt events, and attached purchase-order documents. A key with inventory:read can review current balances and complete stock-out counts by product and warehouse. A key with reorder:read can review configured reorder points, current stock, committed demand, projected availability, and status counts. A key with certifications:read can browse authorized certification types, records, subjects, dates, and evidence filenames. A key with purchase-order-documents:write can preview and attach one document to a visible purchase order. A key with reports:read can discover and run available sales, purchasing, open-order, pipeline, and customer receivables reports, including settlement behavior, credit exposure, and invoice charges. A key with cost-book-entries:read can read current Cost Book entries, exact product, supplier, and ship-from 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 current-cost-sources:read can read a product's fixed, selected, unconfigured, or unavailable supplier-and-origin source state. A key with current-cost-sources:write can preview, set, replace, or clear an eligible supplier-location Current Source after current access is checked. A key with price-book-entries:read can review active, scheduled, expired, and historical configured sale prices with exact package and base-unit context. A key with price-book-entries:write can preview and apply one exact price update after the acting user's current Pricing Engine access and customer visibility are checked. A key with customers:write can create or patch bounded public customer profile, location, address, and attached document fields. A key with products:write can create and update bounded product records and product families, attach product documents, and assign the current Product SDS.

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.

Full access keys include the current public scope set, including tags:read, inventory:read, reorder:read, certifications:read, current-cost-sources:read, and current-cost-sources:write, automatically. Restricted keys receive only the scopes selected for their workflow.

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.

Guardrail

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 document uploads, search, Entity Resolution, Tags, Product Directory, Certification Intelligence, notes, opportunities, contacts, customers, suppliers, company reference, products, product families, Cost Book entries, Current Source, Price Book entries, orders, purchase orders, inventory balances, reorder status, reports, and write readiness. documentUploads.create reports whether the key can prepare an upload. entityResolution.viewableClasses lists the customer, supplier, product, product-family, sales-order, and purchase-order classes the key and acting user can currently resolve. tags.vocabulary reports tag-directory access and tags.viewableEntityTypes lists the record classes available for tag membership. productDirectory.view reports whether regulatory and name-based product discovery is available. certifications.view reports certification access and certifications.viewableSubjectTypes lists the available supplier, customer, product, and customer-address classes. Note capabilities report subject-note access and activityReport separately. Opportunity capabilities report view, create, update, close, and metadata access. Customer capabilities include nested location, address, and document access. Supplier capabilities include nested ship-from and document access. Product capabilities report view, create, update, document, and SDS access. Product-family capabilities report view, create, and update access. Cost Book capabilities report whether entries can be viewed or created. Current Source capabilities report read and write access separately. Price Book capabilities report read access, write access, and the accepted write currency mode. Company-reference capabilities report whether active directory paging is available for customers and suppliers. Order capabilities report view and changed-record discovery access. Purchase-order capabilities also report execution viewing, current-state refresh, document viewing, and document association. Inventory capabilities report balance viewing and current-state refresh access. Reorder capabilities report status viewing and current-state refresh access. 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, opportunities, contacts, customers, suppliers, child records, products, product families, attached documents, Product SDS, Cost Book entries, Current Source, Price Book entries, and purchase-order 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. Responses may add repairCategory, suggestedAction, validValues, repairContext, 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 /opportunities`, `PATCH /opportunities/{id}`, `POST /opportunities/{id}/close`, `PUT /opportunities/{id}/meta`	`opportunities: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 /purchase-orders/{id}/documents`	`purchase-order-documents:write`
`PUT /products/{id}/sds`	`products:write`
`POST /cost-book-entries`	`cost-book-entries:write`
`PUT /products/{id}/current-cost-source`	`current-cost-sources:write`
`POST /price-book-entries`	`price-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"
  }
}