Updated Api (markdown)

Api.md

@@ -518,4 +518,131 @@ Returns HTTP 200 with an empty page on success.
 
 ## System Scopes
 
+System scopes define special scopes that have metadata attached to them such as a human-redable description, an icon, and flags indicating whether or not they are assigned to newly-created clients (`defaultScope`) or are avilable for dynamically registered clients to request (`allowDynReg`). Clients that are managed through the admin UI/API can have scopes that are not registered as a system scope.
+
+Endpoint: **`/api/scopes`**
+
+### GET /api/scopes
+
+_Requires **ROLE_USER** or **ROLE_ADMIN** access._
+
+Get a list of all system scopes on the system, returns results in `application/json`.
+
+```
+[
+    {
+        "id": 1,
+        "value": "openid",
+        "description": "log in using your identity",
+        "icon": "user",
+        "allowDynReg": true,
+        "defaultScope": true
+    },
+    {
+        "id": 2,
+        "value": "profile",
+        "description": "basic profile information",
+        "icon": "list-alt",
+        "allowDynReg": true,
+        "defaultScope": true
+    },
+    {
+        "id": 3,
+        "value": "email",
+        "description": "email address",
+        "icon": "envelope",
+        "allowDynReg": true,
+        "defaultScope": true
+    },
+    {
+        "id": 4,
+        "value": "address",
+        "description": "physical address",
+        "icon": "home",
+        "allowDynReg": true,
+        "defaultScope": true
+    },
+    {
+        "id": 5,
+        "value": "phone",
+        "description": "telephone number",
+        "icon": "bell",
+        "allowDynReg": true,
+        "defaultScope": true
+    },
+    {
+        "id": 6,
+        "value": "offline_access",
+        "description": "offline access",
+        "icon": "time",
+        "allowDynReg": true,
+        "defaultScope": true
+    }
+]
+```
+
+### POST /api/scopes
+
+_Requires **ROLE_ADMIN** access._
+
+Create a new scope on the system. Message body is an `application/json` object with all information:
+
+```
+{
+    "value": "openid",
+    "description": "log in using your identity",
+    "icon": "user",
+    "allowDynReg": true,
+    "defaultScope": true
+}
+```
+
+The server will return an updated copy of the object in `application/json` format as described under **GET /api/scopes/{id}** on success.
+
+### GET /api/scopes/{id}
+
+_Requires **ROLE_USER** or **ROLE_ADMIN** access._
+
+Get information about a specific scope identified by {id} in the url, in `application/json` format. 
+
+For example, the call to `/api/scope/1` would return:
+
+```
+{
+    "id": 1,
+    "value": "openid",
+    "description": "log in using your identity",
+    "icon": "user",
+    "allowDynReg": true,
+    "defaultScope": true
+}
+```
+
+### PUT /api/blacklist/{id}
+
+_Requires **ROLE_ADMIN** access._
+
+Update the information for the scope identified by {id} in the URL. The request body must be `application/json` describing the entire scope object:
+
+```
+{
+    "id": 1,
+    "value": "openid",
+    "description": "log in using your identity",
+    "icon": "user",
+    "allowDynReg": true,
+    "defaultScope": true
+}
+```
+
+The server will return an updated copy of the object in `application/json` format as described under **GET /api/scope/{id}** on success.
+
+### DELETE /api/scope/{id}
+
+_Requires **ROLE_ADMIN** access._
+
+Deletes the scope with the {id} in the URL. Any clients that are currently registered with the scope will retain this scope value but will no longer have the user-readable text or icon associated with it.
+
+Returns HTTP 200 with an empty page on success.
+
 ## User Site Approvals