Synchronize docs/rest-api.yml with Available scopes table in docs/source/rbac/scopes.md

docs/rest-api.yml

@@ -18,34 +18,37 @@ securityDefinitions:
     authorizationUrl: "/hub/api/oauth2/authorize" # what are the absolute URIs here? is oauth2 correct here or shall we use just authorizations?
     tokenUrl: "/hub/api/oauth2/token"
     scopes:
-      self: Everything a standard user can do
+      self: Metascope, grants access to user's own resources; resolves to (no scope) for services.
-      all: Everything a token owner can do
+      all: Metascope, valid for tokens only. Grants access to everything that the token's owning entity can do.
-      users: Grants access to managing users including reading users’ model, posting activity and starting/stoping users servers
+      admin:users: Grants read, write, create and delete access to users and their authentication state but not their servers or tokens.
-      read:users: Read-only access to the above
+      admin:users:auth_state: Grants access to users' authentication state only.
-      read:users!user=username: Read-only access to a single user's model (example horizontal filter)
+      users: Grants read and write permissions to users' models apart from servers, tokens and authentication state.
-      read:users:name: Read-only access to users' names
+      users:activity: Grants access to read and post users' activity only.
-      read:users:groups: Read-only access to users' groups
+      users:activity!user=username: Update a single user's activity (example horizontal filter).
-      read:users:activity: Read-only access to users' activity
+      read:users: Read-only access to users' models apart from servers, tokens and authentication state.
-      read:users:activity!group=groupname: Read-only access to specific group's users' activity (example horizontal filter)
+      read:users!user=username: As above limited to a specific user (example horizontal filter).
-      users:activity: Update users' activity
+      read:users:name: Read-only access to users' names.
-      users:activity!user=username: Update a single user's activity (example horizontal filter)
+      read:users:roles: Read-only access to a list of users' roles names.
-      users:servers: Grants access to start/stop any server
+      read:users:groups: Read-only access to a list of users' group names.
-      users:servers!server=servername: Limits the above to a specific server (example horizontal filter)
+      read:users:activity: Read-only access to users' activity.
-      read:users:servers: Read-only access to users' servers
+      read:users:activity!group=groupname: Read-only access to specific group's users' activity (example horizontal filter).
-      users:tokens: Grants access to users' token (includes create/revoke a token)
+      admin:users:servers: Grants read, start/stop, create and delete permissions to users' servers and their state.
-      read:users:tokens: Read-only access to users' tokens
+      admin:users:server_state: Grants access to servers' state only.
-      admin:users: Grants access to creating/removing users on top of managing access
+      users:servers: Allows for starting/stopping users' servers in addition to read access to their models. Does not include the server state.
-      admin:users:auth_state: Access users' auth state
+      users:servers!server=servername: Limits the above to a specific server (example horizontal filter).
-      admin:users:servers: Grants access to create/remove users' servers on top of managing access
+      read:users:servers: Read-only access to users' server models. Does not include the server state.
-      admin:users:server_state: Access servers' state
+      users:tokens: Grants read, write, create and delete permissions to users' tokens.
-      groups: Add/remove users from any group
+      read:users:tokens: Read-only access to users' tokens.
-      groups!group=groupname: Add/remove users from a specific group only (example horizontal filter)
+      admin:groups: Grants read, write, create and delete access to groups.
-      read:groups: Read-only access to groups
+      groups: Grants read and write permissions to groups, including adding/removing users to/from groups.
-      admin:groups: Grants access to create/delete groups
+      groups!group=groupname: As above limited to a specific group only (example horizontal filter)
-      read:services: Read-only access to services
+      read:groups: Read-only access to groups.
-      read:hub: Read-only access to detailed information about JupyterHub
+      read:services: Read-only access to service models.
-      proxy: Grants access to proxy's routing table, syncing and notifying about a new proxy
+      read:services:name: Read-only access to service names.
-      shutdown: Grants access to shutdown the Hub
+      read:services:roles: Read-only access to a list of service roles names.
+      read:hub: Read-only access to detailed information about JupyterHub.
+      proxy: Allows for obtaining information about the proxy's routing table, for syncing the Hub with proxy and notifying the Hub about a new proxy.
+      shutdown: Grants access to shutdown the Hub.
 security: # global security, do we want to keep only the apiKey (token: []), change to only oauth2 (with scope self) or have both (either can be used)?
   - token: []
   - oauth2:

docs/source/rbac/scopes.md

@@ -95,7 +95,7 @@ Table 1. Available scopes and their hierarchy
 |       `read:users` | Read-only access to users' models _apart from servers, tokens and authentication state_. |
 |          `read:users:name` | Read-only access to users' names. |
 |          `read:users:roles` | Read-only access to a list of users' roles names. |
-|          `read:users:groups` | Read-only access to users' groups. |
+|          `read:users:groups` | Read-only access to a list of users' group names. |
 |          `read:users:activity` | Read-only access to users' activity. |
 | `admin:users:servers` | Grants read, start/stop, create and delete permissions to users' servers and their state. |
 |    `admin:users:server_state` | Grants access to servers' state only. |