Skip to content

SMQ-226 - Add built-in admin role deletions restrictions to docs #223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dborovcanin merged 5 commits into from
Jun 4, 2025
Merged

SMQ-226 - Add built-in admin role deletions restrictions to docs #223

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1f80edb
Add update roles
JeffMboya Apr 23, 2025
b9c837b
Add update roles
JeffMboya Apr 23, 2025
5fa8c55
Fix CI
JeffMboya Apr 23, 2025
2f5c957
Address comments
JeffMboya May 13, 2025
c8f16f2
Enhance clarity
JeffMboya May 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 67 additions & 52 deletions docs/roles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,32 @@
title: Roles, Role Members, and Role Actions
---


## **Roles**
## **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 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**
## **Base URL**

All API requests use the base URL:
`http://localhost/<entity_type>/<entity_id>`
`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**
### **1. Create a Role**

**POST /role**
Creates a role for the given entity.
Creates a role for the given entity.

**Request Body**:
**Request Body**:

```json
{
Expand All @@ -41,9 +40,9 @@ Creates a role for the given entity.
#### Example for a `Channel`

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

**Response**:
**Response**:

```json
{
Expand All @@ -56,17 +55,17 @@ Creates a role for the given entity.

---

### **2. List Roles**
### **2. List Roles**

**GET /roles**
Retrieves all roles for the given entity.
Retrieves all roles for the given entity.

#### List Roles Example for a `Client`

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

**Response**:
**Response**:

```json
[
Expand All @@ -87,17 +86,17 @@ Retrieves all roles for the given entity.

---

### **3. Retrieve a Role**
### **3. Retrieve a Role**

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

#### Retrieve a Role Example for a `Group`

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

**Response**:
**Response**:

```json
{
Expand All @@ -110,24 +109,32 @@ Fetches details of a specific role.

---

### **4. Delete a Role**
#### 4. **Update a Role**
Copy link
Contributor

@Musilah Musilah May 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### 4. **Update a Role**
### 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.
Deletes the specified role.

#### Delete a Role Example for a `Domain`

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

---

### **5. Add Role Members**
### **6. Add Role Members**

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

**Request Body**:
**Request Body**:

```json
{
Expand All @@ -138,9 +145,9 @@ Adds members to the specified role.
#### Add Role Members Example for a `Client`

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

**Request Body**:
**Request Body**:

```json
{
Expand All @@ -150,30 +157,34 @@ Adds members to the specified role.

---

### **6. List Role Members**
### **7. List Role Members**

**GET /roles/`role_id`/members**
Retrieves all members of the specified role.
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`
`GET http://localhost/channels/<channel_id>/roles/<role_id>/members`

**Response**:
**Response**:

```json

```

---

### **7. Delete Specific Role Members**
### **8. Delete Specific Role Members**

**POST /roles/`role_id`/members/delete**
Deletes specific members from the role.
Deletes specific members from the role.

**Request Body**:
> 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, which would otherwise become inaccessible via the API.

**Request Body**:

```json
{
Expand All @@ -184,9 +195,9 @@ Deletes specific members from the role.
#### Delete Specific Role Members Example for a `Group`

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

**Response**:
**Response**:

```json
{
Expand All @@ -196,24 +207,28 @@ Deletes specific members from the role.

---

### **8. Delete All Role Members**
### **9. Delete All Role Members**

**POST /roles/`role_id`/members/delete-all**
Removes all members from the role.
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`
`POST http://localhost/domains/<domain_id>/roles/<role_id>/members/delete-all`

---

### **9. Add Role Actions**
### **10. Add Role Actions**

**POST /roles/`role_id`/actions**
Adds actions to the specified role.
Adds actions to the specified role.

**Request Body**:
**Request Body**:

```json
{
Expand All @@ -224,46 +239,46 @@ Adds actions to the specified role.
#### Add Role Actions Example for a `Client`

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

---

### **10. List Role Actions**
### **11. List Role Actions**

**GET /roles/`role_id`/actions**
Retrieves all actions of the specified role.
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`
`GET http://localhost/channels/<channel_id>/roles/<role_id>/actions`

**Response**:
**Response**:

```json
["read", "update", "publish"]
```

---

### **11. Delete Specific Role Actions**
### **12. Delete Specific Role Actions**

**POST /roles/`role_id`/actions/delete**
Deletes specific actions from the role.
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`
`POST http://localhost/groups/<group_id>/roles/<role_id>/actions/delete`

---

### **12. Delete All Role Actions**
### **13. Delete All Role Actions**

**POST /roles/`role_id`/actions/delete-all**
Removes all actions from the role.
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`
`POST http://localhost/domains/<domain_id>/roles/<role_id>/actions/delete-all`