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.
Scope list
| Scope | Endpoints |
|---|---|
search:read | GET /search, GET /contacts/{id}, GET /customers/{id}, GET /suppliers/{id}, GET /products/{id} |
notes:write | POST /notes, GET /notes/{id}, PATCH /notes/{id} |
contacts:create | POST /contacts |
contacts:update | PATCH /contacts/{id} |
imports:write | Legacy CSV import validation path only. |
Scope ceiling
A key with only search:read cannot write anything. A key with notes:write can use the notes write surface, but it cannot create contacts unless it also has contacts:create.
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.
Search permissions
Search returns only records the acting user can see. If a caller explicitly asks for a type the acting user cannot access, the request returns 403 missing_permission.
Missing access
The two access errors are distinct.
{
"error": {
"type": "authorization_error",
"code": "missing_scope",
"message": "The API key does not include the required scope.",
"requestId": "request-id"
}
}
{
"error": {
"type": "authorization_error",
"code": "missing_permission",
"message": "The acting user does not have permission for this operation.",
"requestId": "request-id"
}
}