fix: more docs

Unleash · May 18, 2021 · bcc2d91 · bcc2d91
1 parent 1d71d01
commit bcc2d91
Show file tree

Hide file tree

Showing 7 changed files with 287 additions and 60 deletions.
diff --git a/docs/api/admin/feature-toggles-api.md b/docs/api/admin/feature-toggles-api.md
@@ -3,7 +3,7 @@ id: features
 title: /api/admin/features
 ---
 
-> > In order to access the admin API endpoints you need to identify yourself. Unless you're using the `none` authentication method, you'll need to [create an ADMIN token](../../user_guide/api-token) and add an Authorization header using the token.
+> In order to access the admin API endpoints you need to identify yourself. Unless you're using the `none` authentication method, you'll need to [create an ADMIN token](../../user_guide/api-token) and add an Authorization header using the token.
 
 ### Fetching Feature Toggles
 
@@ -192,12 +192,12 @@ If the tuple (type, value) does not already exist, it will be added to the list
 }
 ```
 
-## Success
+**Success**
 
     - Returns _201-CREATED_ if the feature was tagged successfully
     - Creates the tag if needed, then connects the tag to the existing feature
 
-## Failures
+**Failures**
 
     - Returns _404-NOT-FOUND_ if the `type` was not found
 
@@ -207,11 +207,11 @@ If the tuple (type, value) does not already exist, it will be added to the list
 
 Removes the specified tag from the `(type, value)` tuple from the Feature Toggle's list of tags.
 
-## Success
+**Success**
 
     - Returns _200-OK_
 
-## Failures
+**Failures**
 
     - Returns 404 if the tag does not exist
     - Returns 500 if the database could not be reached
@@ -340,52 +340,3 @@ None
   "tags": []
 }
 ```
-
-## Archive
-
-### Fetch archived toggles
-
-`GET http://unleash.host.com/api/admin/archive/features`
-
-Used to fetch list of archived feature toggles
-
-**Example response:**
-
-```json
-{
-  "version": 1,
-  "features": [
-    {
-      "name": "Feature.A",
-      "description": "lorem ipsum",
-      "type": "release",
-      "enabled": false,
-      "stale": false,
-      "strategies": [
-        {
-          "name": "default",
-          "parameters": {}
-        }
-      ],
-      "variants": [],
-      "tags": [],
-      "strategy": "default",
-      "parameters": {}
-    }
-  ]
-}
-```
-
-### Revive feature toggle
-
-`POST http://unleash.host.com/api/admin/archive/revive`
-
-**Body:**
-
-```json
-{
-  "name": "Feature.A"
-}
-```
-
-Used to revive a feature toggle.
diff --git a/docs/api/admin/feature-toggles-archive-api.md b/docs/api/admin/feature-toggles-archive-api.md
@@ -0,0 +1,53 @@
+---
+id: features-archive
+title: /api/admin/archive
+---
+
+> In order to access the admin API endpoints you need to identify yourself. Unless you're using the `none` authentication method, you'll need to [create an ADMIN token](../../user_guide/api-token) and add an Authorization header using the token.
+
+### Fetch archived toggles
+
+`GET http://unleash.host.com/api/admin/archive/features`
+
+Used to fetch list of archived feature toggles
+
+**Example response:**
+
+```json
+{
+  "version": 1,
+  "features": [
+    {
+      "name": "Feature.A",
+      "description": "lorem ipsum",
+      "type": "release",
+      "enabled": false,
+      "stale": false,
+      "strategies": [
+        {
+          "name": "default",
+          "parameters": {}
+        }
+      ],
+      "variants": [],
+      "tags": [],
+      "strategy": "default",
+      "parameters": {}
+    }
+  ]
+}
+```
+
+### Revive feature toggle
+
+`POST http://unleash.host.com/api/admin/archive/revive`
+
+**Body:**
+
+```json
+{
+  "name": "Feature.A"
+}
+```
+
+Used to revive a feature toggle.
diff --git a/docs/api/admin/user-admin.md b/docs/api/admin/user-admin.md
@@ -0,0 +1,215 @@
+---
+id: user-admin
+title: /api/admin/user-admin
+---
+
+> In order to access the admin API endpoints you need to identify yourself. Unless you're using the `none` authentication method, you'll need to [create an ADMIN token](../../user_guide/api-token) and add an Authorization header using the token.
+
+### List all users
+
+`GET https://unleash.host.com/api/admin/user-admin`
+
+Will return all users and all available root roles for the Unleash instance.
+
+**Body**
+
+```json
+{
+  "rootRoles": [
+    {
+      "description": "Users with the global admin role have superuser access to Unleash and can perform any operation within the unleash platform.",
+      "id": 1,
+      "name": "Admin",
+      "project": null,
+      "type": "root"
+    },
+    {
+      "description": "Users with this role have access most features in Unleash, but can not manage users and roles in the global scope. If a user with a global regular role creates a project, they will become a project admin and receive superuser rights within the context of that project.",
+      "id": 2,
+      "name": "Editor",
+      "project": null,
+      "type": "root"
+    },
+    {
+      "description": "Users with this role can only read root resources in Unleash. They may be added as collaborator to specific projects.",
+      "id": 3,
+      "name": "Viewer",
+      "project": null,
+      "type": "root"
+    }
+  ],
+  "users": [
+    {
+      "createdAt": "2021-05-14T08:56:34.859Z",
+      "email": "random-user@getunleash.ai",
+      "id": 3,
+      "imageUrl": "https://gravatar.com/avatar/3066e45cf3a09d9a4b51e08a3ac20749?size=42&default=retro",
+      "inviteLink": "",
+      "isAPI": false,
+      "loginAttempts": 0,
+      "rootRole": 1,
+      "seenAt": null
+    },
+    {
+      "createdAt": "2021-05-14T08:58:07.891Z",
+      "email": "random-user2@getunleash.ai",
+      "id": 4,
+      "imageUrl": "https://gravatar.com/avatar/90047524992cd6ae8f66e249a7630d80?size=42&default=retro",
+      "inviteLink": "",
+      "isAPI": false,
+      "loginAttempts": 0,
+      "rootRole": 1,
+      "seenAt": null
+    }
+  ]
+}
+```
+
+### Search for users
+
+You can also search for users via the search API. It will preform a simple search based on name and email matching the given query. Requires minimum 2 characters.
+
+`GET http://localhost:4242/api/admin/user-admin/search?q=iv`
+
+**Body**
+
+```json
+[
+  {
+    "email": "iva2@some-mail.com",
+    "id": 19,
+    "imageUrl": "https://gravatar.com/avatar/6c795493735ff1864f17d47ec52cf0ec?size=42&default=retro"
+  },
+  {
+    "email": "ivar@another.com",
+    "id": 20,
+    "imageUrl": "https://gravatar.com/avatar/f4b3e16a54bfbe824eb814479053bf88?size=42&default=retro"
+  }
+]
+```
+
+### Add a new user
+
+`POST https://unleash.host.com/api/admin/user-admin`
+
+Creates a new use with the given root role.
+
+**Body**
+
+```json
+{
+  "email": "some-email@getunleash.io",
+  "name": "Some Name",
+  "rootRole": 2
+}
+```
+
+**Notes**
+
+- `rootRole` can either be the role id or the unique name of the role (e.g: `Editor`).
+
+#### Return values:
+
+`201: Created`
+
+```json
+{
+  "createdAt": "2021-05-18T10:28:23.067Z",
+  "email": "some-email@getunleash.io",
+  "emailSent": true,
+  "id": 1337,
+  "imageUrl": "https://gravatar.com/avatar/222f2ab70c039dda12e3d11acdcebd02?size=42&default=retro",
+  "inviteLink": "http://localhost:4242/new-user?token=123",
+  "isAPI": false,
+  "loginAttempts": 0,
+  "name": "Some Name",
+  "rootRole": 2,
+  "seenAt": null
+}
+```
+
+`400: Bad request`
+
+```json
+[
+  {
+    "msg": "User already exists"
+  }
+]
+```
+
+`400: Bad request`
+
+```json
+[
+  {
+    "msg": "You must specify username or email"
+  }
+]
+```
+
+### Update a user
+
+`POST https://unleash.host.com/api/admin/user-admin/:userId`
+
+Updates use with new fields
+
+**Body**
+
+```json
+{
+  "email": "some-email@getunleash.io",
+  "name": "Some Name",
+  "rootRole": 2
+}
+```
+
+**Notes**
+
+- `userId` is required as a url path parameter.
+- All fields are optional. Only provided fields are updated.
+
+### Delete a user
+
+`DELETE https://unleash.host.com/api/admin/user-admin/:userId`
+
+Deletes the user with the given `userId`.
+
+Possible return values:
+
+- `200: OK` - user was deleted
+- `404: NOT FOUND` - No user with the provided `userId` was found
+
+### Change password for a user
+
+`POST https://unleash.host.com/api/admin/user-admin/:userId/change-password`
+
+**Body**
+
+```json
+{
+  "password": "k!5As3HquUrQ"
+}
+```
+
+Return values:
+
+- `200 OK`: Password was changed.
+- `400 Bad Request`: Password was not changed. Unleash requires a strong password. Please see in the response body on how to improve the password.
+
+### Validate password for a user
+
+You can use this endpoint to validate the strength of a given password.
+
+`http POST http://localhost:4242/api/admin/user-admin/validate-password`
+
+**Body**
+
+```json
+{
+  "password": "some-simple"
+}
+```
+
+- `200 OK`: Password is strong enough for Unleash.
+- `400 Bad Request`: Unleash requires a stronger password. Please see in the response body on how to improve the password.
diff --git a/docs/user_guide/rbac.md b/docs/user_guide/rbac.md
@@ -28,7 +28,8 @@ Unleash v4 allows you control access to both "root resources" and individual pro
 Unleash will come with three "root" role out of the box:
 
 - **Admin** - Used to administer the Unleash instance. Is allowed to add/remove users, add them to roles and update role permissions.
-- **Editor** - Represent users with typical read and write access to Unleash. They will typically be allowed to create new projects (for enterprise), create feature toggles on the "default" project, configure context fields etc. They will not be able to add/remove users or roles. -- **Viewer** - Users with this role are only allowed to read resources in Unleash. They might be added as collaborators to specific projects.
+- **Editor** - Represent users with typical read and write access to Unleash. They will typically be allowed to create new projects (for enterprise), create feature toggles on the "default" project, configure context fields etc. They will not be able to add/remove users or roles.
+- **Viewer** - Users with this role are only allowed to read resources in Unleash. They might be added as collaborators to specific projects.
 
 ### Project
 

diff --git a/src/lib/routes/admin-api/user-admin.ts b/src/lib/routes/admin-api/user-admin.ts
@@ -127,7 +127,7 @@ export default class UserAdminController extends Controller {
                     username,
                     email,
                     name,
-                    rootRole: Number(rootRole),
+                    rootRole,
                 },
                 user,
             );
@@ -184,7 +184,7 @@ export default class UserAdminController extends Controller {
                     id: Number(id),
                     name,
                     email,
-                    rootRole: Number(rootRole),
+                    rootRole,
                 },
                 user,
             );
@@ -204,8 +204,7 @@ export default class UserAdminController extends Controller {
             await this.userService.deleteUser(+id, user);
             res.status(200).send();
         } catch (error) {
-            this.logger.warn(error);
-            res.status(500).send();
+            handleErrors(res, this.logger, error);
         }
     }