@devx-retailos/admin-extensions

Medusa plugin that adds the /admin/retailos/* API surface and Medusa Admin UI pages for managing retailOS organizations, stores, roles, permissions, and user-role assignments. It is the HTTP layer over @devx-retailos/rbac — the RBAC module itself ships no routes.

Part of retailOS, a Medusa v2 SDK for offline-store POS systems. Packages are installed independently and composed in a brand's Medusa backend.

Installation

npm install @devx-retailos/admin-extensions @devx-retailos/rbac

Peer dependencies: @medusajs/framework, @medusajs/medusa, @medusajs/admin-sdk, @medusajs/admin-shared (^2.15.0), @medusajs/ui (^4.0.0), and react (^18 || ^19).

@devx-retailos/rbac must be registered in the same backend — every route resolves the RBAC module from the container.

Setup

Register both plugins in medusa-config.ts:

plugins: [
  {
    resolve: "@devx-retailos/rbac",
    options: {},
  },
  {
    resolve: "@devx-retailos/admin-extensions",
    options: {},
  },
],

API routes

All routes live under /admin and require an authenticated Medusa admin session. This package does not enforce retailOS permission keys itself; GET /admin/retailos/me/permissions reports them so frontends (e.g. @devx-retailos/sdk-client) can gate UI.

| Method | Path | What it does | | --- | --- | --- | | GET | /admin/retailos/me/permissions | Resolve the calling admin user to a subject; returns { subject, scope, permissions, flags } | | GET | /admin/retailos/organizations | List organizations | | POST | /admin/retailos/organizations | Create an organization (name, slug, metadata?) | | GET | /admin/retailos/organizations/:id | Retrieve an organization | | POST | /admin/retailos/organizations/:id | Update an organization | | DELETE | /admin/retailos/organizations/:id | Delete with cascade (see below) | | GET | /admin/retailos/stores | List stores | | POST | /admin/retailos/stores | Create a store (organization_id, name, code, address?, metadata?) | | GET | /admin/retailos/stores/:id | Retrieve a store | | POST | /admin/retailos/stores/:id | Update a store | | DELETE | /admin/retailos/stores/:id | Delete with cascade (see below) | | GET | /admin/retailos/roles | List roles | | POST | /admin/retailos/roles | Create a role (name, display_name, organization_id?, parent_id?, level?, …) | | GET | /admin/retailos/roles/:id | Retrieve a role | | POST | /admin/retailos/roles/:id | Update a role | | DELETE | /admin/retailos/roles/:id | Delete a role | | POST | /admin/retailos/roles/:id/permissions | Grant a permission to a role (permission_id, granted?, conditions?) | | DELETE | /admin/retailos/roles/:id/permissions | Revoke a permission from a role (body: permission_id) | | GET | /admin/retailos/permissions | List all registered permission keys | | GET | /admin/retailos/user-roles | List role assignments | | POST | /admin/retailos/user-roles | Assign a role to a subject (subject_id, subject_type, role_id, organization_id, store_id?, expires_at?, …) | | DELETE | /admin/retailos/user-roles/:id | Revoke a role assignment |

Inputs are validated with Zod; invalid bodies return 400 with field-level errors.

Cascading deletes

DELETE on an organization or store cleans up dependent data across installed retailOS modules and returns a cascade summary (stores_deleted, store_details_deleted, footfall_entries_deleted, employees_deactivated, roles_deleted, user_roles_deleted, role_permissions_deleted). The store-details, footfall, and employee modules are resolved optionally — cascades skip whatever isn't installed.

Admin UI

Adds an Organizations page to the Medusa Admin sidebar (route /retailos/organizations) listing organizations by name, slug, and creation date.

Optional integrations

• @devx-retailos/feature-flags — when installed, GET /admin/retailos/me/permissions includes resolved feature flags for the subject's scope; otherwise flags is {}.
• @devx-retailos/store-details, @devx-retailos/footfall, @devx-retailos/employee — participate in delete cascades when installed.

Related packages

• @devx-retailos/rbac — the underlying organizations/stores/roles/permissions module (required)
• @devx-retailos/sdk-client — typed frontend client for these routes, plus React hooks
• @devx-retailos/feature-flags — feature flags surfaced via the me/permissions endpoint
• @devx-retailos/employee — employee entities tied to stores
• @devx-retailos/core — shared types, errors, Logger

License

MIT