Assigning and Unassigning Roles to a User¶

Overview¶

The IED Auth API allows administrators to assign and unassign roles to users. This functionality is restricted to administrators and can only be performed on other users, not on themselves.

Server url¶

https://<my-ip/dns>/device/edge/a.service/beta/api/v1

Getting the Role Information¶

Endpoint¶

GET /system/roles

Example Request¶

curl -X GET \
https://<my-ip/dns>/device/edge/a.service/beta/api/v1/system/roles \
-H "Authorization: Bearer <token>"

Response¶

{
  "roles": [
    {
      "id": "6ea7d6ca-d388-4480-8e6f-0a37e2a3ccad",
      "name": "Admin",
      "description": "Admin role"
    },
    {
      "id": "de504955-9f38-489f-b8fb-c744ee3d6190",
      "name": "User",
      "description": "User role"
    }
  ]
}

Retrieve User Information¶

To assign a role to a user, the first step is to get the user ID. You can use the Invited Users API to get the available users on the device and their user IDs.

For information on how to use the API, see the How To: List Invited Users.

Assigning Roles to a User¶

To assign roles to a user, use the following endpoint:

Endpoint¶

POST /users/{userId}/roles

Parameters¶

userId (path): The ID of the user to whom the roles will be assigned.

Request Body¶

{
  "roles": [
    { "id": "role-id-1" },
    { "id": "role-id-2" }
  ]
}

Example Request¶

curl -X POST \
https://<my-ip/dns>/device/edge/a.service/beta/api/v1/users/{userId}/roles \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "roleId": "<role-id>"
}'

Responses¶

201 Created: Roles successfully assigned.
400 Bad Request: Invalid input.
401 Unauthorized: Authentication token is missing or invalid.
403 Forbidden: Insufficient privileges.
409 Conflict: Role already assigned.
500 Internal Server Error: Something went wrong.

Unassigning Roles from a User¶

To unassign roles from a user, use the following endpoint:

Endpoint¶

DELETE /users/{userId}/roles/{roleId}

Parameters¶

userId (path): The ID of the user from whom the roles will be unassigned.

Request Body¶

{
  "roles": [
    { "id": "role-id-1" },
    { "id": "role-id-2" }
  ]
}

Example Request¶

curl -X DELETE \
https://<my-ip/dns>/device/edge/a.service/beta/api/v1/users/{userId}/roles/{roleId} \
-H "Authorization: Bearer <token>"

Responses¶

200 OK: Roles successfully unassigned.
400 Bad Request: Invalid input.
401 Unauthorized: Authentication token is missing or invalid.
403 Forbidden: Insufficient privileges.
409 Conflict: Role is not assigned.
500 Internal Server Error: Something went wrong.

List Roles of a User¶

    curl -X GET \
    https://<my-ip/dns>/device/edge/a.service/beta/api/v1/users/<user_id>/roles \
    -H "Authorization: Bearer <token>"

Notes¶

Only administrators can assign or unassign roles.
Administrators cannot assign or unassign roles to themselves.

For more details, refer to the API specs