Channels

Channel management service for Magistrala — create and configure communication channels, connect clients, manage access control and route messages between devices and applications.

The Channels service manages communication channels in Magistrala. A channel is a message topic that clients connect to for pub/sub messaging. The service handles channel creation, configuration, client connections, group hierarchy, and role-based access control. It exposes both HTTP and gRPC APIs.

Configuration

Variable	Description	Default
`MG_CHANNELS_LOG_LEVEL`	Log level (debug, info, warn, error)	info
`MG_CHANNELS_HTTP_HOST`	HTTP host	localhost
`MG_CHANNELS_HTTP_PORT`	HTTP port	9005
`MG_CHANNELS_GRPC_HOST`	gRPC host	localhost
`MG_CHANNELS_GRPC_PORT`	gRPC port	7005
`MG_CHANNELS_DB_HOST`	Database host	localhost
`MG_CHANNELS_DB_PORT`	Database port	5432
`MG_CHANNELS_DB_USER`	Database user	magistrala
`MG_CHANNELS_DB_PASS`	Database password	magistrala
`MG_CHANNELS_DB_NAME`	Database name	channels
`MG_CHANNELS_DB_SSL_MODE`	SSL mode (disable, require, verify-ca, verify-full)	disable
`MG_CHANNELS_CACHE_URL`	Redis cache URL	redis://localhost:6379/0
`MG_JAEGER_URL`	Jaeger tracing endpoint	http://jaeger:4318/v1/traces
`MG_SEND_TELEMETRY`	Send telemetry to Magistrala call-home server	true

Database Schema

`channels` table

Column	Type	Description
`id`	VARCHAR(36)	UUID primary key
`name`	VARCHAR(1024)	Human-readable name
`domain_id`	VARCHAR(36)	Owning domain
`parent_group_id`	VARCHAR(36)	Optional parent group
`tags`	TEXT[]	Arbitrary tags
`metadata`	JSONB	Free-form structured metadata
`status`	SMALLINT	0 = enabled, 1 = disabled
`route`	VARCHAR(36)	Optional unique identifier for routing within a domain

`connections` table

Column	Type	Description
`channel_id`	VARCHAR(36)	Channel UUID
`domain_id`	VARCHAR(36)	Domain of channel and client
`client_id`	VARCHAR(36)	Client UUID
`type`	SMALLINT	1 = Publish, 2 = Subscribe

Deployment

git clone https://github.com/absmach/magistrala
cd magistrala

make channels
make install

MG_CHANNELS_LOG_LEVEL=info \
MG_CHANNELS_HTTP_HOST=localhost \
MG_CHANNELS_HTTP_PORT=9005 \
MG_CHANNELS_DB_HOST=localhost \
MG_CHANNELS_DB_PORT=5432 \
MG_CHANNELS_DB_USER=magistrala \
MG_CHANNELS_DB_PASS=magistrala \
MG_CHANNELS_DB_NAME=channels \
MG_CHANNELS_CACHE_URL=redis://localhost:6379/0 \
$GOBIN/magistrala-channels

HTTP API

Base URL defaults to http://localhost:9005. All endpoints require Authorization: Bearer <token> and a <domainID> path prefix.

Operation	Description
`create`	Create one or more channels
`get`	Retrieve a channel by ID
`list`	Page and filter channels in a domain
`update`	Update name, metadata, tags, or route
`delete`	Permanently delete a channel
`enable`/`disable`	Toggle channel active state
`set-parent`	Assign a parent group
`remove-parent`	Detach from parent group
`connect`	Connect clients to channels
`disconnect`	Remove client-channel connections
`create-role`	Create an RBAC role on a channel
`add-role-member`	Add users to a channel role

Create a channel

curl -X POST "http://localhost:9005/<domainID>/channels" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sensor-readings",
    "metadata": { "unit": "celsius" },
    "route": "temp-lab",
    "tags": ["sensor", "lab"]
  }'

Connect clients to a channel

curl -X POST "http://localhost:9005/<domainID>/channels/connect" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_ids": ["<chanID>"],
    "client_ids": ["<clientID>"],
    "types": ["publish", "subscribe"]
  }'

Disconnect clients from a channel

curl -X POST "http://localhost:9005/<domainID>/channels/disconnect" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_ids": ["<chanID>"],
    "client_ids": ["<clientID>"],
    "types": ["publish"]
  }'

Health check

curl http://localhost:9005/health

Best Practices

Use route when a channel needs a predictable human-readable identifier for message routing.
Use tags and metadata to categorize channels by environment, region, or purpose.
Keep channel hierarchies shallow — avoid deep nesting unless the use case demands it.
Use disable instead of delete when you want to temporarily suspend a channel.
Regularly audit client-channel connections and remove stale links.
Grant clients only the connection type they actually need (Publish or Subscribe, not both by default).

For the full API reference, see the API documentation.

On this page