Users

Magistrala CLI provides a simple and efficient way to manage users. Below are the key commands to create, authenticate, and manage users within your system.

Create User

To create a user using Magistrala-CLI, run the following command:

magistrala-cli users create <first_name> <last_name> <email> <username> <password>

This command registers a new user with the provided details.

Example usage:

 magistrala-cli users create jane doe janicedoe@example.com janicedoe 12345678

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "janicedoe"
  },
  "email": "janicedoe@example.com",
  "first_name": "jane",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "doe",
  "role": "user",
  "status": "enabled",
  "updated_at": "0001-01-01T00:00:00Z"
}

⚠️ Note: Ensure that usernames are unique to prevent conflicts.

To log in and obtain an access token:

magistrala-cli users token [<user_email>|<username>] <user_password>

Since v0.14.0, Magistrala supports domains. Domains are used to separate different tenants, and almost all the activities in Magistrala happen under a particular domain. Only three major types of actions do not happen within a domain: login where you get to list domains and log in to them, and invitations management to accept domain membership sent by other users as well the creation of new users. An access token with a domain is required for all the other actions on Clients, Channels, and Groups. To authenticate within a specific domain, use:

magistrala-cli users token <user_email> <user_password> <domain_id>

Example usage:

magistrala-cli users token admin 12345678

Expected response:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkyOTQxMjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MCwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.Qot3ZoqC1enhAS3YEJY3WJioMAJnr98laBGsJzSgF2Zege5pVqILVLcPZzRBmHdIPys4diAGbqRQQzfW_k_Huw",
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkzNzY5MjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MSwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.EcRH3DUZcplHz-9Ry_90kSQKLwAWXPww9XfMZ9beoEJItpY39g5-n7vnTyLkRhOp6Pw6aZbfuhOL3TWIE-Q13A"
}

Refresh User Token

If the access token has expired, you can obtain a new one using the refresh token:

magistrala-cli users refreshtoken <refresh_token>

Example usage:

magistrala-cli users refreshtoken eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkzNzY5MjcsImlhdCI6MTczOTI5MDUyNywiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MSwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.EcRH3DUZcplHz-9Ry_90kSQKLwAWXPww9XfMZ9beoEJItpY39g5-n7vnTyLkRhOp6Pw6aZbfuhOL3TWIE-Q13A

Expected response:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkyOTQ2MTQsImlhdCI6MTczOTI5MTAxNCwiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MCwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.MlAUDZYNg2D5Bj9m6IAaXe6wo-U1-q4OpLjrB9TMfg30W1J0ybp2KE_cMfAzMyLUY-Kk_d1e0WYGgIUg7Rgm-Q",
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzkzNzc0MTQsImlhdCI6MTczOTI5MTAxNCwiaXNzIjoic3VwZXJtcS5hdXRoIiwidHlwZSI6MSwidXNlciI6IjZjY2FmMTNjLWVmODgtNGNmMi04ZTNhLWM3YzA0YzVlYWY5YiJ9.FQNUwTQPVxas9l1p6ywy7UYO4Dc4rpgbkyMhzPSY20A9JMXFWYh43bxQugu4CsE3eAnp5Zxk9QXxKjmrKIMGiA"
}

Retrieve a Specific User

To get details of a specific user:

magistrala-cli users get <user_id> <user_token>

Example usage:

26ae3198-6060-4308-824c-c846953b9898 token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "janicedoe"
  },
  "email": "janicedoe@example.com",
  "first_name": "jane",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "doe",
  "role": "user",
  "status": "enabled",
  "updated_at": "0001-01-01T00:00:00Z"
}

Retrieve All Users

To list all users:

magistrala-cli users get all <user_token>

Example usage:

magistrala-cli users get all token

Expected response:

{
  "limit": 10,
  "offset": 0,
  "total": 2,
  "users": [
    {
      "created_at": "2025-02-11T16:14:03.503217Z",
      "credentials": {
        "username": "admin"
      },
      "email": "admin@example.com",
      "first_name": "super",
      "id": "6ccaf13c-ef88-4cf2-8e3a-c7c04c5eaf9b",
      "last_name": "admin",
      "metadata": {
        "role": "admin"
      },
      "role": "admin",
      "status": "enabled",
      "updated_at": "0001-01-01T00:00:00Z"
    },
    {
      "created_at": "2025-02-11T16:15:12.607701Z",
      "credentials": {
        "username": "janicedoe"
      },
      "email": "janicedoe@example.com",
      "first_name": "jane",
      "id": "26ae3198-6060-4308-824c-c846953b9898",
      "last_name": "doe",
      "role": "user",
      "status": "enabled",
      "updated_at": "0001-01-01T00:00:00Z"
    }
  ]
}

Update User Information

Using the update flag can update the user's names, tags, metadata, email as well as username.

Update User Names

To update a user's names:

magistrala-cli users update <user_id> '{"first_name":"new first_name", "last_name":"new last_name"}' <user_token>

Example usage:

magistrala-cli users update 26ae3198-6060-4308-824c-c846953b9898 '{"first_name":"Janice", "last_name":"Doe"}' token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "janicedoe"
  },
  "email": "janicedoe@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "role": "user",
  "status": "enabled",
  "updated_at": "2025-02-11T16:34:52.377144Z"
}

Update User Metadata

To update a user's metadata:

magistrala-cli users update <user_id> '{"metadata":{"value2": "value3"}}' <user_token>

Example usage:

magistrala-cli users update 26ae3198-6060-4308-824c-c846953b9898 '{"metadata":{"aoty": "1"}}'  token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "janicedoe"
  },
  "email": "janicedoe@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "enabled",
  "updated_at": "2025-02-11T16:36:56.188559Z"
}

Update User Tags

To update a user's tags:

magistrala-cli users update tags <user_id> '["tag1", "tag2"]' <user_token>

Example usage:

magistrala-cli users update tags 26ae3198-6060-4308-824c-c846953b9898 '["light 1", "light 2"]' token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "janicedoe"
  },
  "email": "janicedoe@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "enabled",
  "tags": [
    "light 1",
    "light 2"
  ],
  "updated_at": "2025-02-11T16:44:11.670547Z"
}

Update User Email

To update a user's email:

magistrala-cli users update email <user_id> <user_email> <user_token>

Example usage:

magistrala-cli users update email 26ae3198-6060-4308-824c-c846953b9898 Janice@example.com  token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "janicedoe"
  },
  "email": "Janice@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "enabled",
  "tags": [
    "lemonade",
    "renaissance"
  ],
  "updated_at": "2025-02-11T16:45:36.288667Z"
}

Update Username

To update a user's username:

magistrala-cli users update username <user_id> <new_username> <user_token>

Example usage:

magistrala-cli users update username 26ae3198-6060-4308-824c-c846953b9898 Janice  token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "Janice"
  },
  "email": "Janice@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "enabled",
  "tags": [
    "lemonade",
    "renaissance"
  ],
  "updated_at": "2025-02-11T16:46:55.951208Z"
}

Update User Password

To update a user's password:

magistrala-cli users password <old_password> <password> <user_token>

Example usage:

magistrala-cli users password 12345678 123456789 token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "Janice"
  },
  "email": "Janice@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "enabled",
  "tags": [
    "lemonade",
    "renaissance"
  ],
  "updated_at": "2025-02-11T17:12:50.101988Z"
}

Reset User Password Request

To send a request to reset a user's password:

magistrala-cli users resetpasswordrequest <email>

Reset User Password

To reset a user's password:

magistrala-cli users resetpassword <password> <confpass> <password_request_token>

Enable User

To enable a user's status:

magistrala-cli users enable <user_id> <user_token>

Example usage:

magistrala-cli users enable 26ae3198-6060-4308-824c-c846953b9898 token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "Janice"
  },
  "email": "Janice@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "enabled",
  "tags": [
    "lemonade",
    "renaissance"
  ],
  "updated_at": "2025-02-11T17:16:50.323734Z"
}

Disable User

To disable a user:

magistrala-cli users disable <user_id> <user_token>

Example usage:

magistrala-cli users disable 26ae3198-6060-4308-824c-c846953b9898 token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "Janice"
  },
  "email": "Janice@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "disabled",
  "tags": [
    "lemonade",
    "renaissance"
  ],
  "updated_at": "2025-02-11T17:15:17.096604Z"
}

Delete User

To delete a user:

magistrala-cli users delete <user_id> <user_token>

Example usage:

magistrala-cli users delete 28a8be12-f3eb-4917-851b-30bf04ea04a0 token

This will return an OK response.

Get Profile of the User

To get the profile details of the currently authenticated user:

magistrala-cli users profile <user_token>

Example usage:

magistrala-cli users profile token

Expected response:

{
  "created_at": "2025-02-11T16:15:12.607701Z",
  "credentials": {
    "username": "Janice"
  },
  "email": "Janice@example.com",
  "first_name": "Janice",
  "id": "26ae3198-6060-4308-824c-c846953b9898",
  "last_name": "Doe",
  "metadata": {
    "aoty": "1"
  },
  "role": "user",
  "status": "enabled",
  "tags": [
    "lemonade",
    "renaissance"
  ],
  "updated_at": "2025-02-11T17:16:50.323734Z"
}

Search User

To search for a specific user using queries:

magistrala-cli users search <query> <user_token>

Create User​

Login User​

Refresh User Token​

Retrieve a Specific User​

Retrieve All Users​

Update User Information​

Update User Names​

Update User Metadata​

Update User Tags​

Update User Email​

Update Username​

Update User Password​

Reset User Password Request​

Reset User Password​

Enable User​

Disable User​

Delete User​

Get Profile of the User​

Search User​

Create User

Login User

Refresh User Token

Retrieve a Specific User

Retrieve All Users

Update User Information

Update User Names

Update User Metadata

Update User Tags

Update User Email

Update Username

Update User Password

Reset User Password Request

Reset User Password

Enable User

Disable User

Delete User

Get Profile of the User

Search User