Skip to content

roles.md

Latest commit

 

History

History
284 lines (187 loc) · 5.59 KB

roles.md

File metadata and controls

284 lines (187 loc) · 5.59 KB
title
Roles, Role Members, and Role Actions

Roles

A role is a collection of permissions (actions) that define what members of the role are allowed to do within a specific entity. Each entity (like a Client, Channel, Group, or Domain) can have multiple roles, each with its own members and actions.

  • Role Members: These are users assigned to a role. Members are the only users allowed to perform the role's actions on the entity.
  • Role Actions: These are permissions defining what members of the role can do. For example, actions can include read, update, delete, or more specific actions like publish or connect_to_channel. Refer to authz-spec.md for the available actions for each entity type.

Base URL

All API requests use the base URL:
http://localhost/<entity_type>/<entity_id>

Replace <entity_type> with one of the entity types (clients, channels, groups, domains) and <entity_id> with the ID of the specific entity.

Endpoints and Examples

1. Create a Role

POST /role
Creates a role for the given entity.

Request Body:

{
  "role_name": "member",
  "optional_actions": ["read"],
  "optional_members": ["user_1"]
}

Example for a Channel

Request:
POST http://localhost/channels/<channel_id>/role

Response:

{
  "role_id": "id_xxxxx",
  "role_name": "member",
  "actions": ["read"],
  "members": ["user_1"]
}

2. List Roles

GET /roles
Retrieves all roles for the given entity.

List Roles Example for a Client

Request:
GET http://localhost/clients/<client_id>/roles

Response:

[
  {
    "role_id": "xxxxx",
    "role_name": "Admin",
    "actions": ["read", "update", "delete"],
    "members": ["user_1", "user_2"]
  },
  {
    "role_id": "xxxxx",
    "role_name": "Viewer",
    "actions": ["read"],
    "members": ["user_3"]
  }
]

3. Retrieve a Role

GET /roles/role_id
Fetches details of a specific role.

Retrieve a Role Example for a Group

Request:
GET http://localhost/groups/<group_id>/roles/<role_id>

Response:

{
  "role_id": "xxxxx",
  "role_name": "Admin",
  "actions": ["read", "update", "delete"],
  "members": ["user_1", "user_2"]
}

4. Update a Role

PUT /roles/roleID

Updates the role's name, actions, or other properties.

5. Delete a Role

DELETE /roles/role_id
Deletes the specified role.

Delete a Role Example for a Domain

Request:
DELETE http://localhost/domains/<domain_id>/roles/<role_id>

6. Add Role Members

POST /roles/role_id/members
Adds members to the specified role.

Request Body:

{
  "members": ["user_4"]
}

Add Role Members Example for a Client

Request:
POST http://localhost/clients/<client_id>/roles/<role_id>/members

Request Body:

{
  "members": ["user_4"]
}

7. List Role Members

GET /roles/role_id/members
Retrieves all members of the specified role.

List Role Members Example for a Channel

Request:
GET http://localhost/channels/<channel_id>/roles/<role_id>/members

Response:





8. Delete Specific Role Members


POST /roles/role_id/members/delete

Deletes specific members from the role.




If the role being modified is the built-in admin role, the system will reject the request if it would result in removing all remaining members from the role.


This restriction ensures that every domain always retains at least one administrator to prevent orphaned domains.




Request Body:


{
  "members": ["user_4"]
}


Delete Specific Role Members Example for a Group


Request:

POST http://localhost/groups/<group_id>/roles/<role_id>/members/delete


Response:


{
  "message": "Members removed successfully"
}




9. Delete All Role Members


POST /roles/role_id/members/delete-all

Removes all members from the role.




For the built-in admin role, this operation is not permitted.

The system will reject any request that attempts to remove all members from the admin role to prevent administrative lockout.

This ensures that every domain retains at least one user with administrative privileges at all times.




Delete All Role Members Example for a Domain


Request:

POST http://localhost/domains/<domain_id>/roles/<role_id>/members/delete-all




10. Add Role Actions


POST /roles/role_id/actions

Adds actions to the specified role.


Request Body:


{
  "actions": ["publish"]
}


Add Role Actions Example for a Client


Request:

POST http://localhost/clients/<client_id>/roles/<role_id>/actions




11. List Role Actions


GET /roles/role_id/actions

Retrieves all actions of the specified role.


List Role Actions Example for a Channel


Request:

GET http://localhost/channels/<channel_id>/roles/<role_id>/actions


Response:


["read", "update", "publish"]




12. Delete Specific Role Actions


POST /roles/role_id/actions/delete

Deletes specific actions from the role.


Delete Specific Role Actions Example for a Group


Request:

POST http://localhost/groups/<group_id>/roles/<role_id>/actions/delete




13. Delete All Role Actions


POST /roles/role_id/actions/delete-all

Removes all actions from the role.


Delete All Role Actions Example for a Domain


Request:

POST http://localhost/domains/<domain_id>/roles/<role_id>/actions/delete-all