User Role

Introduction

Users do not have a directly assigned role. Instead, each user is linked to one or more groups, which define their rights and possible actions on the platform.

User groups allow for structuring permissions and assigning rights based on the environments in which a user can operate.

Structure of Roles and Groups

Fundamental Principle

• A user does not have a direct role.
• A user is always linked to one or more groups.
• A group defines access rights and possible actions on the platform.

Group Management

• A group can contain multiple users.
• A user can be assigned to multiple groups simultaneously.
• A group carries the permissions associated with a specific environment.

Environments and Permissions

Each user group is limited to a specific environment and has roles that allow for executing certain actions on the platform.

Types of Environments

User groups can be created to manage actions in three distinct environments:

Examples of Roles and Permissions

Groups can include several specific permissions, such as:

• FOC (Front Office Customer)
  • Access to visible products and catalogs.
  • Order management.
  • Viewing prices and offers.
  • ORDER_VALIDATE — controls whether the user can validate (place) their own orders. When set to false, the user cannot exit checkout on their own orders.
  • ORDER_VALIDATE_ON_ALL_ACCOUNT — extends validation rights to orders of other users in the same account. Combined with ORDER_VALIDATE=false, the user can only validate orders of other users, never their own.
• Back Office Operator
  • Management of products and catalogs.
  • Order administration.
  • Management of prices and commercial offers.
• Back Office Supplier
  • Management of a supplier’s specific products and offers.
  • Viewing and updating stock levels.
  • Tracking orders related to their company.

📌 Note: A user can only perform an action if one of their groups has the necessary permission in the relevant environment.

Managing Groups and Roles

Group and role management is available to customers, either in self-service or operated by the Customer Success team. The module provides the following capabilities:

• Roles grouped by typology — roles are returned and displayed grouped by category rather than as a flat list, making large permission sets easier to navigate. Typologies follow a one-typology-per-business-entity convention ("Entity management"): Product management, Assortment management, Order management, Payment management, Data Hub management, Store and store view management, and so on. Each role appears under the entity it relates to, and this classification does not change the permissions themselves.
• Functional description per role — each role carries a one-sentence description explaining, in plain language, what it concretely allows. The description is shown next to the role name.
• Group renaming — a group can be renamed at any time (both in the Back Office UI and via the API).
• Users tab on all group types — the list of users is available for Operator and Supplier groups, in addition to Account groups.
• Role creation — new roles can be created directly from the Back Office.
• Session refresh after a permission change — when a user's rights change, the session is refreshed (JWT reconnection) so the new permissions take effect.

📘

Note: The endpoints for managing groups and roles are published in the DJUST API reference. Refer to the API reference for the available routes and operationIds.

Group Membership Rule — At Least One Group

A user must belong to at least one group at all times. The "no group" state — which would leave a user with no access at all — is not valid. Multi-group membership is still allowed: a user can belong to one or many groups; only the empty state is forbidden.

This rule is enforced server-side, so a direct API call (curl, Postman, or a third-party integration) cannot bypass it. Adding and removing a user from a group remain two independent operations — there is no forced "move".

Operations Guarded by the Rule

In all these cases the API returns a clear message: "The user must be attached to at least one group."

✅

Tip: To move a user between groups without hitting this rule, add the new group first, then remove the old one. Users already belonging to multiple groups are unaffected — there is no migration.

Change History (Audit Log)

An admin, paginated endpoint — ADM-GROUP-ROLES-HISTORY-550 — exposes the chronological history of permission changes on the groups & roles module — who changed what, and when. This audit trail supports investigation, security, and compliance use cases.

GET /v1/group-roles/history
dj-client: OPERATOR
dj-api-key: {{apiKey}}

📘

Note: This endpoint is tenant-level (the dj-store / dj-store-view headers are ignored). It requires dj-client: OPERATOR and the ALL_USER_GROUPS_READ role. The history is append-only: events cannot be edited or deleted, and no such endpoints are exposed.

The same history is also available in the Back Office, in a dedicated History tab of the Groups & Roles page (visible to users with the ALL_USER_GROUPS_READ role). The view requires selecting a client type (Operator / Account / Supplier) and offers combinable filters on group, author, date range, and action type — matching the API filters described below.

Logged Event Types

Event Fields

✅

Tip: Names, emails, and group names are frozen at the moment of the event. A user who is later deleted, or a group that is later renamed or removed, remains readable in the history with its original values.

Query Parameters

Filters combine with AND across different parameters and OR across the values of a single multi-valued parameter. Results are sorted by createdAt:desc by default.

Example — Recent Role Changes on a Group

GET /v1/group-roles/history?clientType=OPERATOR&groupId=grp-buyers&eventType=ADD_ROLE&eventType=REMOVE_ROLE&size=20
dj-client: OPERATOR
dj-api-key: {{apiKey}}

{
  "content": [
    {
      "id": "evt-10293",
      "createdAt": "2026-06-28T14:12:07Z",
      "eventType": "ADD_ROLE",
      "clientType": "OPERATOR",
      "user": { "id": "op-001", "email": "[email protected]", "fullName": "Admin Acme" },
      "role": { "id": "ORDER_VALIDATE", "name": "Validate orders" },
      "group": { "id": "grp-buyers", "name": "Buyers" }
    },
    {
      "id": "evt-10288",
      "createdAt": "2026-06-27T09:41:55Z",
      "eventType": "RENAME_GROUP",
      "clientType": "OPERATOR",
      "user": { "id": "op-001", "email": "[email protected]", "fullName": "Admin Acme" },
      "group": { "id": "grp-buyers", "name": "Buyers" },
      "previousValue": "Purchasers"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

⚠️

Warning: clientType is mandatory. Omitting it returns 400 Bad Request.

Best Practices and Limitations

Best Practices

• Structure groups based on operational needs.
• Avoid assigning too many permissions to a single group for better access management.
• Always verify the permissions assigned to groups to prevent unwanted access.
• Use separate groups for each environment to comply with role management rules.

Known Limitations

• A group can belong to only one environment.
• A user must belong to at least one group at all times — enforced server-side (see Group Membership Rule).
• Permissions are defined at the group level and cannot be assigned directly to users.