Security, Roles & Permissions

This page clarifies who can do what on Operations, which headers are required, and how admin vs shop scopes differ.

Keep in mind

• Feature flag: the tenant-level flag OPERATIONS must be enabled, otherwise the feature is not accessible.
• Least privilege: only authorized users can create or modify Operations.
• Scope-aware: admin vs shop endpoints, store scoping, and account eligibility all apply.
• Immutable type: once set to PUBLIC or PRIVATE, the type cannot be changed.
• Owner edits: only the creator/owner can modify an Operation.

🧑‍🤝‍🧑 Roles

• Operator: platform operator with full admin visibility; can set type=PUBLIC.
• Customer User (admin right): may create and manage their own Operations in admin; cannot set type=PUBLIC; on PRIVATE, can attach only Accounts they are attached to.
• Customer User (buyer): shop/front role; can list and use ACTIVE Operations available to their Account and Store.

graph LR
  %% ---------- Actors ----------
  OP[Operator]
  CUADM[Customer User<br>with admin right]
  CUBUY[Customer User<br>buyer]

  %% ---------- Endpoints ----------
  ADMIN[Admin endpoints<br>/v1/operations...]
  SHOP[Shop endpoints<br>/v1/shop/operations...]

  %% ---------- Flows ----------
  OP --> ADMIN
  CUADM --> ADMIN
  CUBUY --> SHOP

  %% ---------- Styles (shared palette) ----------
  classDef total fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef diff fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef acct fill:#f5e9ff,stroke:#8a2be2,stroke-width:2px,color:#3b0764;
  classDef view fill:#ede9fe,stroke:#7c3aed,stroke-width:1.5px,color:#1e1b4b;
  classDef union fill:#e9d5ff,stroke:#6d28d9,stroke-width:1.5px,color:#3b0764;
  classDef visible fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef op fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#065f46;
  classDef inter fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef resp fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  class OP total;
  class CUADM,CUBUY acct;
  class ADMIN op;
  class SHOP view;

  style OP rx:8,ry:8
  style CUADM rx:8,ry:8
  style CUBUY rx:8,ry:8
  style ADMIN rx:8,ry:8
  style SHOP rx:8,ry:8

  %% Accent key links (index by edge order)
  linkStyle 0 stroke:#2f6feb,stroke-width:2px
  linkStyle 2 stroke:#7c3aed,stroke-width:2px

Operators can see any Operation in admin. Customer Users (admin right) can see and manage only their own Operations.

🧾 Required headers

All API calls must include standard Djust headers (no new parameters invented here):

• dj-client: OPERATOR (admin) or ACCOUNT (shop/admin depending on context)
• dj-api-key: required
• dj-store, dj-store-view: optional, used for store scoping

For shop calls, dj-client=ACCOUNT is expected. For admin, dj-client may be OPERATOR or ACCOUNT depending on who operates the endpoint. Shop constraint: for buyer endpoints (e.g., /v1/shop/operations, /v1/shop/operations/{operationId}, /v1/shop/operations/{operationId}/lines), only dj-client=ACCOUNT is accepted; other values must be rejected.

⚙️ Permissions matrix (summary)

“own only” = the user is the creator/owner of the Operation. Deletion is blocked if any cart or order is linked.

🛡️ Access flow (high-level)

graph LR
  %% ---------- Flow ----------
  A[Incoming request] --> FF[Feature flag OPERATIONS<br>enabled?]
  FF -->|No| DENY[403 Feature disabled]
  FF -->|Yes| H[Headers check<br>dj-client, dj-api-key, store]
  H --> R[Role and rights check]
  R --> O[Ownership check<br>if admin user]
  O --> S[Status and dates check<br>Active and within window<br>shop context]
  S --> V[Visibility checks<br>type, store, account]
  V --> C[Catalog Views check<br>for product lines]
  C --> OK[Allow]

  %% ---------- Styles (shared palette) ----------
  classDef total fill:#e8f1ff,stroke:#2f6feb,stroke-width:2px,color:#0b3d91;
  classDef diff fill:#fff4e5,stroke:#f59e0b,stroke-width:2px,color:#7a3e00;
  classDef acct fill:#f5e9ff,stroke:#8a2be2,stroke-width:2px,color:#3b0764;
  classDef view fill:#ede9fe,stroke:#7c3aed,stroke-width:1.5px,color:#1e1b4b;
  classDef union fill:#e9d5ff,stroke:#6d28d9,stroke-width:1.5px,color:#3b0764;
  classDef visible fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#064e3b;
  classDef op fill:#e0f7fa,stroke:#06b6d4,stroke-width:2px,color:#065f46;
  classDef inter fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d;
  classDef resp fill:#f2f4f7,stroke:#475569,stroke-width:2px,color:#111827;

  class FF total;
  class H resp;
  class R,O acct;
  class S diff;
  class V view;
  class C union;
  class OK visible;
  class DENY inter;

  style A rx:8,ry:8
  style FF rx:8,ry:8
  style DENY rx:8,ry:8
  style H rx:8,ry:8
  style R rx:8,ry:8
  style O rx:8,ry:8
  style S rx:8,ry:8
  style V rx:8,ry:8
  style C rx:8,ry:8
  style OK rx:8,ry:8

  %% Accent key links (edge order: 0..8)
  linkStyle 1 stroke:#ef4444,stroke-width:2px
  linkStyle 8 stroke:#10b981,stroke-width:2px

• Admin flow emphasizes role and ownership.
• Shop flow emphasizes status/date, store/account eligibility, then Catalog Views for product lines.

🧭 Admin vs Shop scope

• Admin (/v1/operations...): create, edit (DRAFT), attach accounts (PRIVATE), publish/deactivate, duplicate, delete.
• Shop (/v1/shop/operations...): read-only visibility for buyers; only ACTIVE Operations within dates and store scope; product lines filtered by Catalog Views.

🔒 Locking rules (recap)

• Lines and accounts are editable only in DRAFT.
• Type (PUBLIC/PRIVATE) is immutable once chosen.
• Deleting an Operation is blocked if linked carts or orders exist.

🔗 API quicklinks (read‑only)

• Admin: POST|GET|PUT|PATCH|DELETE /v1/operations{...}, /v1/operations/{operationId}/lines, /v1/operations/{operationId}/accounts
• Shop: GET /v1/shop/operations, GET /v1/shop/operations/{operationId}, GET /v1/shop/operations/{operationId}/lines

Follow existing contracts and operationId conventions. Do not introduce new parameters or fields.