Roles and Privileges

Model: each business route runs a privilege check before the handler. It validates the caller’s JWT (issued by AWS Cognito), reads the custom:privileges IAM policy on the token, checks the required action, and populates the request user.

  • Token invalid/missing/expired/malformed → AUTH_TOKEN_INVALID (401).
  • Privilege not granted → AUTH_INSUFFICIENT_PERMISSIONS (403).
  • Elevated Resource values *, admin, superadmin → the user is treated as an admin. Resource: self (and legacy guest/viewer) → individual scope, enabling ownership checks (order’s tracked user vs token username).
  • An admin-only mode additionally requires the admin flag (not used by the current routes, which pass a bare privilege).
  • SKIP_AUTH=true bypasses JWT only when no Bearer token is present (local/dev calls). If a token is present, it is still validated and privileges are enforced.

Full privilege list (all privileges used across routes):

Privilege Used by
oms:createOrder create order, create return order
oms:viewOrder list/get orders, SKU, counts, order summary, returns list, return labels, list tasks
oms:updateOrder patch/cancel/split/notes/notifications, return lifecycle, return-collection callback, event resend
oms:deleteOrder delete order
oms:processOrder complete/fail workflow task
oms:viewInvoice list/get invoices, invoices-by-order
oms:createInvoice create invoice
oms:updateInvoice patch / put invoice
oms:deleteInvoice delete invoice
oms:viewPayment get payment
oms:createPayment create payment
oms:updatePayment update payment
oms:deletePayment delete payment
oms:viewInstance get instances, get/list instance attributes
oms:createInstance create instance, create instance attribute
oms:updateInstance update/patch instance, update instance attribute
oms:deleteInstance delete instance, delete instance attribute

There is no dedicated “admin role” endpoint; admin behaviour is derived from the elevated Resource on the token (ADMIN_REQUIRED/FORBIDDEN codes apply to delete/resend-style guards).

Revision History
2026-08-05 | JP – Created the page and added the content.