Skip to content

Commit 5deca2d

Browse files
JeffMboyaJeffMboya
authored
SMQ-226 - Add built-in admin role deletions restrictions to docs (#223)
* Add update roles Signed-off-by: JeffMboya <[email protected]> * Add update roles Signed-off-by: JeffMboya <[email protected]> * Fix CI Signed-off-by: JeffMboya <[email protected]> * Address comments Signed-off-by: JeffMboya <[email protected]> * Enhance clarity Signed-off-by: JeffMboya <[email protected]> --------- Signed-off-by: JeffMboya <[email protected]>
1 parent e39bd58 commit 5deca2d

File tree

1 file changed

+67
-52
lines changed

1 file changed

+67
-52
lines changed

‎docs/roles.md‎

Lines changed: 67 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -2,33 +2,32 @@
22
title: Roles, Role Members, and Role Actions
33
---
44

5-
6-
## **Roles**
5+
## **Roles**
76

87
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.
98

10-
- **Role Members**: These are users assigned to a role. Members are the only users allowed to perform the role's actions on the entity.
9+
- **Role Members**: These are users assigned to a role. Members are the only users allowed to perform the role's actions on the entity.
1110
- **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.**
1211

1312
---
1413

15-
## **Base URL**
14+
## **Base URL**
1615

1716
All API requests use the base URL:
18-
`http://localhost/<entity_type>/<entity_id>`
17+
`http://localhost/<entity_type>/<entity_id>`
1918

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

2221
---
2322

2423
### **Endpoints and Examples**
2524

26-
### **1. Create a Role**
25+
### **1. Create a Role**
2726

2827
**POST /role**
29-
Creates a role for the given entity.
28+
Creates a role for the given entity.
3029

31-
**Request Body**:
30+
**Request Body**:
3231

3332
```json
3433
{
@@ -41,9 +40,9 @@ Creates a role for the given entity.
4140
#### Example for a `Channel`
4241

4342
**Request**:
44-
`POST http://localhost/channels/<channel_id>/role`
43+
`POST http://localhost/channels/<channel_id>/role`
4544

46-
**Response**:
45+
**Response**:
4746

4847
```json
4948
{
@@ -56,17 +55,17 @@ Creates a role for the given entity.
5655

5756
---
5857

59-
### **2. List Roles**
58+
### **2. List Roles**
6059

6160
**GET /roles**
62-
Retrieves all roles for the given entity.
61+
Retrieves all roles for the given entity.
6362

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

6665
**Request**:
67-
`GET http://localhost/clients/<client_id>/roles`
66+
`GET http://localhost/clients/<client_id>/roles`
6867

69-
**Response**:
68+
**Response**:
7069

7170
```json
7271
[
@@ -87,17 +86,17 @@ Retrieves all roles for the given entity.
8786

8887
---
8988

90-
### **3. Retrieve a Role**
89+
### **3. Retrieve a Role**
9190

9291
**GET /roles/`role_id`**
93-
Fetches details of a specific role.
92+
Fetches details of a specific role.
9493

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

9796
**Request**:
98-
`GET http://localhost/groups/<group_id>/roles/<role_id>`
97+
`GET http://localhost/groups/<group_id>/roles/<role_id>`
9998

100-
**Response**:
99+
**Response**:
101100

102101
```json
103102
{
@@ -110,24 +109,32 @@ Fetches details of a specific role.
110109

111110
---
112111

113-
### **4. Delete a Role**
112+
### 4. **Update a Role**
113+
114+
**PUT /roles/`roleID`**
115+
116+
Updates the role's name, actions, or other properties.
117+
118+
---
119+
120+
### **5. Delete a Role**
114121

115122
**DELETE /roles/`role_id`**
116-
Deletes the specified role.
123+
Deletes the specified role.
117124

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

120127
**Request**:
121-
`DELETE http://localhost/domains/<domain_id>/roles/<role_id>`
128+
`DELETE http://localhost/domains/<domain_id>/roles/<role_id>`
122129

123130
---
124131

125-
### **5. Add Role Members**
132+
### **6. Add Role Members**
126133

127134
**POST /roles/`role_id`/members**
128-
Adds members to the specified role.
135+
Adds members to the specified role.
129136

130-
**Request Body**:
137+
**Request Body**:
131138

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

140147
**Request**:
141-
`POST http://localhost/clients/<client_id>/roles/<role_id>/members`
148+
`POST http://localhost/clients/<client_id>/roles/<role_id>/members`
142149

143-
**Request Body**:
150+
**Request Body**:
144151

145152
```json
146153
{
@@ -150,30 +157,34 @@ Adds members to the specified role.
150157

151158
---
152159

153-
### **6. List Role Members**
160+
### **7. List Role Members**
154161

155162
**GET /roles/`role_id`/members**
156-
Retrieves all members of the specified role.
163+
Retrieves all members of the specified role.
157164

158165
#### List Role Members Example for a `Channel`
159166

160167
**Request**:
161-
`GET http://localhost/channels/<channel_id>/roles/<role_id>/members`
168+
`GET http://localhost/channels/<channel_id>/roles/<role_id>/members`
162169

163-
**Response**:
170+
**Response**:
164171

165172
```json
166173

167174
```
168175

169176
---
170177

171-
### **7. Delete Specific Role Members**
178+
### **8. Delete Specific Role Members**
172179

173180
**POST /roles/`role_id`/members/delete**
174-
Deletes specific members from the role.
181+
Deletes specific members from the role.
175182

176-
**Request Body**:
183+
> 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.
184+
>
185+
> This restriction ensures that **every domain always retains at least one administrator** to prevent orphaned domains.
186+
187+
**Request Body**:
177188

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

186197
**Request**:
187-
`POST http://localhost/groups/<group_id>/roles/<role_id>/members/delete`
198+
`POST http://localhost/groups/<group_id>/roles/<role_id>/members/delete`
188199

189-
**Response**:
200+
**Response**:
190201

191202
```json
192203
{
@@ -196,24 +207,28 @@ Deletes specific members from the role.
196207

197208
---
198209

199-
### **8. Delete All Role Members**
210+
### **9. Delete All Role Members**
200211

201212
**POST /roles/`role_id`/members/delete-all**
202-
Removes all members from the role.
213+
Removes all members from the role.
214+
215+
> For the built-in `admin` role, this operation is **not permitted**.
216+
> The system will reject any request that attempts to remove all members from the `admin` role to **prevent administrative lockout**.
217+
> This ensures that **every domain retains at least one user with administrative privileges** at all times.
203218
204219
#### Delete All Role Members Example for a `Domain`
205220

206221
**Request**:
207-
`POST http://localhost/domains/<domain_id>/roles/<role_id>/members/delete-all`
222+
`POST http://localhost/domains/<domain_id>/roles/<role_id>/members/delete-all`
208223

209224
---
210225

211-
### **9. Add Role Actions**
226+
### **10. Add Role Actions**
212227

213228
**POST /roles/`role_id`/actions**
214-
Adds actions to the specified role.
229+
Adds actions to the specified role.
215230

216-
**Request Body**:
231+
**Request Body**:
217232

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

226241
**Request**:
227-
`POST http://localhost/clients/<client_id>/roles/<role_id>/actions`
242+
`POST http://localhost/clients/<client_id>/roles/<role_id>/actions`
228243

229244
---
230245

231-
### **10. List Role Actions**
246+
### **11. List Role Actions**
232247

233248
**GET /roles/`role_id`/actions**
234-
Retrieves all actions of the specified role.
249+
Retrieves all actions of the specified role.
235250

236251
#### List Role Actions Example for a `Channel`
237252

238253
**Request**:
239-
`GET http://localhost/channels/<channel_id>/roles/<role_id>/actions`
254+
`GET http://localhost/channels/<channel_id>/roles/<role_id>/actions`
240255

241-
**Response**:
256+
**Response**:
242257

243258
```json
244259
["read", "update", "publish"]
245260
```
246261

247262
---
248263

249-
### **11. Delete Specific Role Actions**
264+
### **12. Delete Specific Role Actions**
250265

251266
**POST /roles/`role_id`/actions/delete**
252-
Deletes specific actions from the role.
267+
Deletes specific actions from the role.
253268

254269
#### Delete Specific Role Actions Example for a `Group`
255270

256271
**Request**:
257-
`POST http://localhost/groups/<group_id>/roles/<role_id>/actions/delete`
272+
`POST http://localhost/groups/<group_id>/roles/<role_id>/actions/delete`
258273

259274
---
260275

261-
### **12. Delete All Role Actions**
276+
### **13. Delete All Role Actions**
262277

263278
**POST /roles/`role_id`/actions/delete-all**
264-
Removes all actions from the role.
279+
Removes all actions from the role.
265280

266281
#### Delete All Role Actions Example for a `Domain`
267282

268283
**Request**:
269-
`POST http://localhost/domains/<domain_id>/roles/<role_id>/actions/delete-all`
284+
`POST http://localhost/domains/<domain_id>/roles/<role_id>/actions/delete-all`

0 commit comments

Comments
 (0)