groups

Groups

The Groups service exposes HTTP and gRPC APIs for organizing entities into hierarchical groups within a domain, managing membership, permissions, and roles. It handles group lifecycle (create/update/enable/disable/delete), parent/child relationships, listings (flat or tree), and role-based access.

For a deeper overview of SuperMQ, see the official documentation.

Configuration

The service is configured via environment variables (unset values fall back to defaults).

Note: Set SMQ_GROUPS_CALLOUT_OPERATIONS to a subset of OpCreateGroup, OpViewGroup, OpUpdateGroup, OpEnableGroup, OpDisableGroup, OpDeleteGroup, OpListGroups, OpHierarchy, OpAddParentGroup, OpRemoveParentGroup, OpAddChildrenGroups, OpRemoveChildrenGroups, OpRemoveAllChildrenGroups, or OpListChildrenGroups to filter which actions produce callouts.

Deployment

The service ships as a Docker container. See the groups section in docker-compose.yaml for deployment configuration.

To build and run locally:

# download the latest version of the service
git clone https://github.com/absmach/supermq
cd supermq

# compile the groups service
make groups

# copy binary to $GOBIN
make install

# set the environment variables and run the service
SMQ_GROUPS_LOG_LEVEL=debug \
SMQ_GROUPS_HTTP_HOST=groups \
SMQ_GROUPS_HTTP_PORT=9004 \
SMQ_GROUPS_HTTP_SERVER_CERT="" \
SMQ_GROUPS_HTTP_SERVER_KEY="" \
SMQ_GROUPS_GRPC_HOST=groups \
SMQ_GROUPS_GRPC_PORT=7004 \
SMQ_GROUPS_GRPC_SERVER_CERT="" \
SMQ_GROUPS_GRPC_SERVER_KEY="" \
SMQ_GROUPS_GRPC_SERVER_CA_CERTS="" \
SMQ_GROUPS_GRPC_CLIENT_CA_CERTS="" \
SMQ_GROUPS_DB_HOST=groups-db \
SMQ_GROUPS_DB_PORT=5432 \
SMQ_GROUPS_DB_USER=supermq \
SMQ_GROUPS_DB_PASS=supermq \
SMQ_GROUPS_DB_NAME=groups \
SMQ_GROUPS_DB_SSL_MODE=disable \
SMQ_GROUPS_DB_SSL_CERT="" \
SMQ_GROUPS_DB_SSL_KEY="" \
SMQ_GROUPS_DB_SSL_ROOT_CERT="" \
SMQ_AUTH_GRPC_URL="" \
SMQ_AUTH_GRPC_TIMEOUT=1s \
SMQ_AUTH_GRPC_CLIENT_CERT="" \
SMQ_AUTH_GRPC_CLIENT_KEY="" \
SMQ_AUTH_GRPC_SERVER_CA_CERTS="" \
SMQ_DOMAINS_GRPC_URL=domains:7003 \
SMQ_DOMAINS_GRPC_TIMEOUT=1s \
SMQ_DOMAINS_GRPC_CLIENT_CERT="" \
SMQ_DOMAINS_GRPC_CLIENT_KEY="" \
SMQ_DOMAINS_GRPC_SERVER_CA_CERTS="" \
SMQ_CHANNELS_GRPC_URL=channels:7005 \
SMQ_CHANNELS_GRPC_TIMEOUT=1s \
SMQ_CHANNELS_GRPC_CLIENT_CERT="" \
SMQ_CHANNELS_GRPC_CLIENT_KEY="" \
SMQ_CHANNELS_GRPC_SERVER_CA_CERTS="" \
SMQ_CLIENTS_GRPC_URL=clients:7000 \
SMQ_CLIENTS_GRPC_TIMEOUT=1s \
SMQ_CLIENTS_GRPC_CLIENT_CERT="" \
SMQ_CLIENTS_GRPC_CLIENT_KEY="" \
SMQ_CLIENTS_GRPC_SERVER_CA_CERTS="" \
SMQ_SPICEDB_HOST=localhost \
SMQ_SPICEDB_PORT=50051 \
SMQ_SPICEDB_SCHEMA_FILE=schema.zed \
SMQ_SPICEDB_PRE_SHARED_KEY=12345678 \
SMQ_ES_URL=nats://localhost:4222 \
SMQ_JAEGER_URL=<http://localhost:4318/v1/traces> \
SMQ_JAEGER_TRACE_RATIO=1.0 \
SMQ_GROUPS_CALLOUT_URLS="" \
SMQ_GROUPS_CALLOUT_METHOD=POST \
SMQ_GROUPS_CALLOUT_TLS_VERIFICATION=false \
SMQ_GROUPS_CALLOUT_TIMEOUT=10s \
SMQ_GROUPS_CALLOUT_CA_CERT="" \
SMQ_GROUPS_CALLOUT_CERT="" \
SMQ_GROUPS_CALLOUT_KEY="" \
SMQ_GROUPS_CALLOUT_OPERATIONS="" \
SMQ_SEND_TELEMETRY=true \
SMQ_GROUPS_INSTANCE_ID="" \
$GOBIN/supermq-groups

Usage

Groups supports the following operations:

API Examples

Create a Group

curl -X POST http://localhost:9004/<domainID>/groups \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "edge-devices",
    "description": "All edge devices",
    "metadata": { "region": "eu-west-1" },
    "tags": ["iot","edge"],
    "parent_id": "",
    "status": "enabled"
  }'

List Groups (flat)

curl -X GET "http://localhost:9004/<domainID>/groups?limit=10&status=enabled" \
  -H "Authorization: Bearer <your_access_token>"

Retrieve a Group (with Roles)

curl -X GET "http://localhost:9004/<domainID>/groups/<groupID>?roles=true" \
  -H "Authorization: Bearer <your_access_token>"

Update a Group

curl -X PUT http://localhost:9004/<domainID>/groups/<groupID> \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "edge-ops",
    "description": "Edge operations",
    "metadata": { "region": "eu-west-1", "env": "prod" },
    "tags": ["iot","ops"]
  }'

Enable or Disable a Group

curl -X POST http://localhost:9004/<domainID>/groups/<groupID>/enable \
  -H "Authorization: Bearer <your_access_token>"

curl -X POST http://localhost:9004/<domainID>/groups/<groupID>/disable \
  -H "Authorization: Bearer <your_access_token>"

Manage Hierarchy

# Add a parent
curl -X POST http://localhost:9004/<domainID>/groups/<groupID>/parents \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "parent_id": "<parentID>" }'

# List children between levels 1 and 2
curl -X GET "http://localhost:9004/<domainID>/groups/<groupID>/children?start_level=1&end_level=2&limit=10" \
  -H "Authorization: Bearer <your_access_token>"

Roles Management for Groups

Group roles use the shared role manager. Supported operations mirror domain roles (create, list, view, update, delete roles; add/list/remove actions; add/list/remove members; list available actions).

Example: create a group role

curl -X POST http://localhost:9004/<domainID>/groups/<groupID>/roles \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "group-admin",
    "optional_actions": ["manage_role_permission", "update_permission"],
    "optional_members": ["<userID>"]
  }'

List available actions for groups:

curl -X GET http://localhost:9004/<domainID>/groups/roles/available-actions \
  -H "Authorization: Bearer <your_access_token>"

Implementation Details

• Groups are stored in PostgreSQL with ltree paths for hierarchy queries; domain migrations are applied alongside group migrations for referential integrity.
• Role tables are provisioned per entity with a groups_ prefix.
• Event notifications are published to SMQ_ES_URL; domain events are consumed to keep group data aligned.
• Authorization and roles are enforced through SpiceDB and shared policy middleware.
• Optional HTTP callouts (pre-operation hooks) are controlled via SMQ_GROUPS_CALLOUT_*.
• Observability: Jaeger tracing, Prometheus metrics at /metrics, and a /health endpoint.

Groups Table

Best Practices

• Model hierarchy deliberately: keep depth reasonable and avoid cycles by design.
• Use tags/metadata to segment groups by environment, region, or ownership for filtering.
• Prefer disable before delete when you need reversible off-boarding.
• Use roles sparingly and audit with list-role-members; grant only required actions.
• Fetch children with bounded levels to keep queries efficient.
• Limit callouts to necessary operations via SMQ_GROUPS_CALLOUT_OPERATIONS.

Versioning and Health Check

The Groups service exposes /health with status and build metadata.

curl -X GET http://localhost:9004/health \
  -H "accept: application/health+json"

Example response:

{
  "status": "pass",
  "version": "0.18.0",
  "commit": "7d6f4dc4f7f0c1fa3dc24eddfb18bb5073ff4f62",
  "description": "groups service",
  "build_time": "1970-01-01_00:00:00"
}

For full API coverage, see the Groups API documentation.