Users

User management service for Magistrala — handles registration, login, profile management, password reset, email verification and account lifecycle.

The Users service provides an HTTP API for managing user accounts on the Magistrala platform. It handles registration, login, profile updates, password reset, email verification, and account lifecycle (enable/disable/delete). It communicates with the Auth service over gRPC for token issuance and validation.

Configuration

Variable	Description	Default
`MG_USERS_LOG_LEVEL`	Log level (debug, info, warn, error)	info
`MG_USERS_ADMIN_EMAIL`	Default admin account created on startup	admin@example.com
`MG_USERS_ADMIN_PASSWORD`	Default admin password	12345678
`MG_USERS_PASS_REGEX`	Password validation regex	`^.{8,}$`
`MG_USERS_HTTP_HOST`	HTTP host	localhost
`MG_USERS_HTTP_PORT`	HTTP port	9002
`MG_USERS_DB_HOST`	Database host	localhost
`MG_USERS_DB_PORT`	Database port	5432
`MG_USERS_DB_USER`	Database user	magistrala
`MG_USERS_DB_PASS`	Database password	magistrala
`MG_USERS_DB_NAME`	Database name	users
`MG_USERS_DB_SSL_MODE`	SSL mode (disable, require, verify-ca, verify-full)	disable
`MG_AUTH_GRPC_URL`	Auth service gRPC URL	localhost:8181
`MG_AUTH_GRPC_TIMEOUT`	Auth service gRPC timeout	1s
`MG_EMAIL_HOST`	SMTP server host	localhost
`MG_EMAIL_PORT`	SMTP server port	25
`MG_EMAIL_USERNAME`	SMTP username	""
`MG_EMAIL_PASSWORD`	SMTP password	""
`MG_EMAIL_FROM_ADDRESS`	Sender email address	""
`MG_EMAIL_FROM_NAME`	Sender display name	""
`MG_PASSWORD_RESET_URL_PREFIX`	URL prefix for password reset links	http://localhost/password/reset
`MG_VERIFICATION_URL_PREFIX`	URL prefix for email verification links	http://localhost/verify-email
`MG_USERS_ES_URL`	Event store URL	nats://localhost:4222
`MG_USERS_DELETE_INTERVAL`	Interval for running the account deletion sweep	24h
`MG_USERS_DELETE_AFTER`	Grace period before a disabled account is permanently deleted	720h
`MG_JAEGER_URL`	Jaeger tracing endpoint	http://localhost:4318/v1/traces
`MG_SEND_TELEMETRY`	Send telemetry to Magistrala call-home server	true

Deployment

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

make users
make install

MG_USERS_LOG_LEVEL=info \
MG_USERS_ADMIN_EMAIL=admin@example.com \
MG_USERS_ADMIN_PASSWORD=12345678 \
MG_USERS_HTTP_HOST=localhost \
MG_USERS_HTTP_PORT=9002 \
MG_USERS_DB_HOST=localhost \
MG_USERS_DB_PORT=5432 \
MG_USERS_DB_USER=magistrala \
MG_USERS_DB_PASS=magistrala \
MG_USERS_DB_NAME=users \
MG_AUTH_GRPC_URL=localhost:8181 \
MG_EMAIL_HOST=smtp.example.com \
MG_EMAIL_PORT=587 \
MG_EMAIL_FROM_ADDRESS=noreply@example.com \
$GOBIN/magistrala-users

Set MG_USERS_HTTP_SERVER_CERT and MG_USERS_HTTP_SERVER_KEY to enable TLS. If MG_EMAIL_HOST is not reachable, the service still starts but password reset emails will not be sent.

HTTP API

Base URL defaults to http://localhost:9002.

Operation	Description
Register	Create a user account
Issue token	Exchange credentials for access/refresh tokens (login)
Refresh token	Obtain a new access token using a refresh token
Profile	Fetch the authenticated user's own profile
View user	Retrieve a user by ID
List users	Page and filter users
Update user	Patch name, metadata, tags, profile picture
Change identity	Update email or username
Change secret	Update password
Enable/Disable	Activate or deactivate an account
Delete	Permanently remove an account
Verify email	Confirm email address via link
Password reset	Request and apply a password reset

Register a user

curl -X POST http://localhost:9002/users \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "credentials": { "username": "ada", "secret": "changeMe123" },
    "email": "ada@example.com"
  }'

curl -X POST http://localhost:9002/users/tokens/issue \
  -H "Content-Type: application/json" \
  -d '{ "identity": "ada@example.com", "secret": "changeMe123" }'

View own profile

curl http://localhost:9002/users/profile \
  -H "Authorization: Bearer $ACCESS_TOKEN"

List users

curl "http://localhost:9002/users?limit=10&status=enabled" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Request password reset

curl -X POST http://localhost:9002/password/reset-request \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com" }'

Health check

curl http://localhost:9002/health

Best Practices

Disable self-registration in production and onboard users via admin tokens.
Require email verification before granting domain roles (MG_ALLOW_UNVERIFIED_USER=false).
Harden passwords with MG_USERS_PASS_REGEX and enforce rotation.
Use MG_USERS_DELETE_AFTER to automatically purge stale disabled accounts.
Store SMTP credentials in a secrets manager, not in image environment.

For the full API reference, see the API documentation.

On this page