Clients

Client management service for Magistrala — provision devices and applications, manage credentials, connect them to channels, and control access via role-based policies.

The Clients service manages the devices and applications that connect to Magistrala. A client represents any entity that publishes or subscribes to messages. The service handles client provisioning, credential management, channel connections, and role-based access control. It exposes both HTTP and gRPC APIs.

Configuration

Variable	Description	Default
`MG_CLIENTS_LOG_LEVEL`	Log level (debug, info, warn, error)	info
`MG_CLIENTS_HTTP_HOST`	HTTP host	localhost
`MG_CLIENTS_HTTP_PORT`	HTTP port	9006
`MG_CLIENTS_GRPC_HOST`	gRPC host	localhost
`MG_CLIENTS_GRPC_PORT`	gRPC port	7000
`MG_CLIENTS_DB_HOST`	Database host	localhost
`MG_CLIENTS_DB_PORT`	Database port	5432
`MG_CLIENTS_DB_USER`	Database user	magistrala
`MG_CLIENTS_DB_PASS`	Database password	magistrala
`MG_CLIENTS_DB_NAME`	Database name	clients
`MG_CLIENTS_DB_SSL_MODE`	SSL mode (disable, require, verify-ca, verify-full)	disable
`MG_CLIENTS_CACHE_URL`	Redis cache URL	redis://localhost:6379/0
`MG_CLIENTS_CACHE_KEY_DURATION`	Cache TTL in seconds	3600
`MG_CLIENTS_ES_URL`	Event store URL	localhost:6379
`MG_AUTH_GRPC_URL`	Auth service gRPC URL	localhost:7001
`MG_AUTH_GRPC_TIMEOUT`	Auth gRPC timeout	1s
`MG_JAEGER_URL`	Jaeger tracing endpoint	http://jaeger:4318/v1/traces
`MG_SEND_TELEMETRY`	Send telemetry to Magistrala call-home server	true

Standalone mode: set MG_CLIENTS_STANDALONE_ID and MG_CLIENTS_STANDALONE_TOKEN to run without the Auth service (useful for edge deployments).

Database Schema

`clients` 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 for hierarchical scoping
`identity`	VARCHAR(254)	Login identity
`secret`	VARCHAR(4096)	Hashed authentication secret
`tags`	TEXT[]	Arbitrary tags
`metadata`	JSONB	Free-form structured metadata
`status`	SMALLINT	0 = enabled, 1 = disabled

`connections` table

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

Deployment

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

make clients
make install

MG_CLIENTS_LOG_LEVEL=info \
MG_CLIENTS_HTTP_HOST=localhost \
MG_CLIENTS_HTTP_PORT=9006 \
MG_CLIENTS_DB_HOST=localhost \
MG_CLIENTS_DB_PORT=5432 \
MG_CLIENTS_DB_USER=magistrala \
MG_CLIENTS_DB_PASS=magistrala \
MG_CLIENTS_DB_NAME=clients \
MG_CLIENTS_CACHE_URL=redis://localhost:6379/0 \
MG_AUTH_GRPC_URL=localhost:7001 \
$GOBIN/magistrala-clients

HTTP API

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

Operation	Description
`create`	Provision one or more clients
`get`	Retrieve a client by ID
`list`	Page and filter clients in a domain
`update`	Update name, metadata, or tags
`delete`	Permanently remove a client
`enable` / `disable`	Toggle client active state
`set-parent-group`	Assign a parent group
`remove-parent-group`	Detach from parent group
`create-role`	Create an RBAC role for the client
`list-roles`	List all roles on a client
`add-role-member`	Add users to a client role

Create a client

curl -X POST "http://localhost:9006/<domainID>/clients" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "temperature-sensor-01",
    "tags": ["edge", "sensor"],
    "metadata": { "model": "DS18B20", "location": "warehouse" }
  }'

List clients

curl "http://localhost:9006/<domainID>/clients?limit=10&status=enabled" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Update a client

curl -X PATCH "http://localhost:9006/<domainID>/clients/<clientID>" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "updated-name", "metadata": { "firmware": "v2.1" } }'

Disable a client

curl -X POST "http://localhost:9006/<domainID>/clients/<clientID>/disable" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Health check

curl http://localhost:9006/health

Best Practices

Use metadata for device attributes (model, firmware version, location) to enable rich filtering.
Rotate client secrets periodically; use disable rather than delete when decommissioning temporarily.
Prefer standalone mode for edge deployments where the Auth service is not reachable.
Review client roles and channel connections regularly to audit access.

For the full API reference, see the API documentation.

On this page