diff --git a/docs/rest-api.yml b/docs/rest-api.yml
index 09d0ed99..0c07e640 100644
--- a/docs/rest-api.yml
+++ b/docs/rest-api.yml
@@ -13,8 +13,40 @@ securityDefinitions:
     type: apiKey
     name: Authorization
     in: header
-security:
+  oauth2:
+    type: oauth2
+    flow: accessCode
+    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:
+      all: Everything a user can do
+      read:all: Read-only access to everything a user can read (also whoami handler)
+      users: Grants access to managing users including reading users’ model, posting activity and starting/stoping users servers
+      read:users: Read-only access to the above
+      read:users!user=username: Read-only access to a single user's model
+      read:users:names: Read-only access to users' names
+      read:users:groups: Read-only access to users' groups
+      read:users:activity: Read-only access to users' activity
+      read:users:activity!group=groupname: Read-only access to specific group's users' activity
+      read:users:servers: Read-only access to users' servers
+      users:activity!user=username: Update a user's activity
+      users:servers: Grants access to start/stop any server
+      users:servers!server=servername: Limits the above to a specific server
+      users:tokens: Grants access to users' token (includes create/revoke a token)
+      read:users:tokens: Identify a user from a token
+      admin:users: Grants access to creating/removing users
+      admin:users:servers: Grants access to create/remove users' servers
+      groups: Add/remove users from any group
+      groups!group=groupname: Add/remove users from a specific group only
+      read:groups: Read-only access to groups
+      admin:groups: Grants access to create/delete groups
+      read:services: Read-only access to services
+      proxy: Grants access to proxy's routing table, syncing and notifying 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 all) or have both (either can be used)?
   - token: []
+  - oauth2:
+    - all
 basePath: /hub/api
 produces:
   - application/json
@@ -79,6 +111,10 @@ paths:
   /users:
     get:
       summary: List users
+      security:
+        - oauth2:
+          - users
+          - read:users
       responses:
         '200':
           description: The Hub's user list
@@ -88,6 +124,9 @@ paths:
               $ref: '#/definitions/User'
     post:
       summary: Create multiple users
+      security:
+        - oauth2:
+          - admin:users
       parameters:
         - name: body
           in: body
@@ -114,6 +153,11 @@ paths:
   /users/{name}:
     get:
       summary: Get a user by name
+      security:
+        - oauth2:
+          - users
+          - read:users
+          - read:users!user=username
       parameters:
         - name: name
           description: username
@@ -127,6 +171,9 @@ paths:
             $ref: '#/definitions/User'
     post:
       summary: Create a single user
+      security:
+        - oauth2:
+          - admin:users
       parameters:
         - name: name
           description: username
@@ -141,6 +188,9 @@ paths:
     patch:
       summary: Modify a user
       description: Change a user's name or admin status
+      security:
+        - oauth2:
+          - users
       parameters:
         - name: name
           description: username
@@ -167,6 +217,9 @@ paths:
             $ref: '#/definitions/User'
     delete:
       summary: Delete a user
+      security:
+        - oauth2:
+          - admin:users
       parameters:
         - name: name
           description: username
@@ -184,6 +237,10 @@ paths:
         Notify the Hub of activity by the user,
         e.g. accessing a service or (more likely)
         actively using a server.
+      security:
+        - oauth2:
+          - users
+          - users:activity!user=username
       parameters:
         - name: name
           description: username
@@ -236,6 +293,10 @@ paths:
   /users/{name}/server:
     post:
       summary: Start a user's single-user notebook server
+      security:
+        - oauth2:
+          - users
+          - users:servers
       parameters:
         - name: name
           description: username
@@ -262,6 +323,10 @@ paths:
           description: The user's notebook server has not yet started, but has been requested
     delete:
       summary: Stop a user's server
+      security:
+        - oauth2:
+          - users
+          - users:servers
       parameters:
         - name: name
           description: username
@@ -276,6 +341,11 @@ paths:
   /users/{name}/servers/{server_name}:
     post:
       summary: Start a user's single-user named-server notebook server
+      security:
+        - oauth2:
+          - users
+          - users:servers
+          - users:servers!server=servername
       parameters:
         - name: name
           description: username
@@ -307,6 +377,11 @@ paths:
           description: The user's notebook named-server has not yet started, but has been requested
     delete:
       summary: Stop a user's named-server
+      security:
+        - oauth2:
+          - users
+          - users:servers
+          - users:servers!server=servername
       parameters:
         - name: name
           description: username
@@ -344,6 +419,9 @@ paths:
         type: string
     get:
       summary: List tokens for the user
+      security:
+        - oauth2:
+          - users:tokens
       responses:
         '200':
           description: The list of tokens
@@ -357,6 +435,9 @@ paths:
           description: No such user
     post:
       summary: Create a new token for the user
+      security:
+        - oauth2:
+          - users:tokens
       parameters:
         - name: token_params
           in: body
@@ -370,6 +451,9 @@ paths:
               note:
                 type: string
                 description: A note attached to the token for future bookkeeping
+              roles:
+                type: list
+                description: A list of role names that the token should have
       responses:
         '201':
           description: The newly created token
@@ -377,6 +461,8 @@ paths:
             $ref: '#/definitions/Token'
         '400':
           description: Body must be a JSON dict or empty
+        '403':
+          description: Requested role does not exist
   /users/{name}/tokens/{token_id}:
     parameters:
       - name: name
@@ -390,6 +476,9 @@ paths:
         type: string
     get:
       summary: Get the model for a token by id
+      security:
+        - oauth2:
+          - users:tokens
       responses:
         '200':
           description: The info for the new token
@@ -397,12 +486,19 @@ paths:
             $ref: '#/definitions/Token'
     delete:
       summary: Delete (revoke) a token by id
+      security:
+        - oauth2:
+          - users:tokens
       responses:
         '204':
           description: The token has been deleted
   /user:
     get:
       summary: Return authenticated user's model
+      security:
+        - oauth2:
+          - all
+          - read:all
       responses:
         '200':
           description: The authenticated user's model is returned.
@@ -411,6 +507,10 @@ paths:
   /groups:
     get:
       summary: List groups
+      security:
+        - oauth2:
+          - groups
+          - read:groups
       responses:
         '200':
           description: The list of groups
@@ -421,6 +521,11 @@ paths:
   /groups/{name}:
     get:
       summary: Get a group by name
+      security:
+        - oauth2:
+          - groups
+          - groups!group=groupname
+          - read:groups
       parameters:
         - name: name
           description: group name
@@ -434,6 +539,9 @@ paths:
             $ref: '#/definitions/Group'
     post:
       summary: Create a group
+      security:
+        - oauth2:
+          - admin:groups
       parameters:
         - name: name
           description: group name
@@ -447,6 +555,9 @@ paths:
             $ref: '#/definitions/Group'
     delete:
       summary: Delete a group
+      security:
+        - oauth2:
+          - admin:groups
       parameters:
         - name: name
           description: group name
@@ -459,6 +570,10 @@ paths:
   /groups/{name}/users:
     post:
       summary: Add users to a group
+      security:
+        - oauth2:
+          - groups
+          - groups!group=groupname
       parameters:
         - name: name
           description: group name
@@ -484,6 +599,10 @@ paths:
             $ref: '#/definitions/Group'
     delete:
       summary: Remove users from a group
+      security:
+        - oauth2:
+          - groups
+          - groups!group=groupname
       parameters:
         - name: name
           description: group name
@@ -508,6 +627,9 @@ paths:
   /services:
     get:
       summary: List services
+      security:
+        - oauth2:
+          - read:services
       responses:
         '200':
           description: The service list
@@ -518,6 +640,9 @@ paths:
   /services/{name}:
     get:
       summary: Get a service by name
+      security:
+        - oauth2:
+          - read:services
       parameters:
         - name: name
           description: service name
@@ -533,6 +658,9 @@ paths:
     get:
       summary: Get the proxy's routing table
       description: A convenience alias for getting the routing table directly from the proxy
+      security:
+        - oauth2:
+          - proxy
       responses:
         '200':
           description: Routing table
@@ -541,12 +669,18 @@ paths:
             description: configurable-http-proxy routing table (see configurable-http-proxy docs for details)
     post:
       summary: Force the Hub to sync with the proxy
+      security:
+        - oauth2:
+          - proxy
       responses:
         '200':
           description: Success
     patch:
       summary: Notify the Hub about a new proxy
       description: Notifies the Hub of a new proxy to use.
+      security:
+        - oauth2:
+          - proxy
       parameters:
         - name: body
           in: body
@@ -579,6 +713,9 @@ paths:
         in the JSON request body.
         Logging in via this method is only available when the active Authenticator
         accepts passwords (e.g. not OAuth).
+      security:
+        - oauth2:
+          - users:tokens # minrk: this is a deprecated alias to POST /users/{name}/tokens, either remove it or use the same scope
       parameters:
         - name: credentials
           in: body
@@ -603,6 +740,9 @@ paths:
   /authorizations/token/{token}:
     get:
       summary: Identify a user or service from an API token
+      security:
+        - oauth2:
+          - read:users:tokens # minrk: is it really necessary to have a scope for this, or use self handler for token whoami?
       parameters:
         - name: token
           in: path
@@ -633,6 +773,7 @@ paths:
             $ref: '#/definitions/User'
         '404':
           description: A user is not found.
+      deprecated: true # minrk: let’s not add a scope for this, let’s remove it
   /oauth2/authorize:
     get:
       summary: 'OAuth 2.0 authorize endpoint'
@@ -714,6 +855,9 @@ paths:
   /shutdown:
     post:
       summary: Shutdown the Hub
+      security:
+        - oauth2:
+          - shutdown
       parameters:
         - name: body
           in: body
@@ -747,6 +891,11 @@ definitions:
       admin:
         type: boolean
         description: Whether the user is an admin
+      roles:
+        type: array
+        description: The names of roles this user has
+        items:
+          type: string
       groups:
         type: array
         description: The names of groups where this user is a member
@@ -828,6 +977,11 @@ definitions:
       admin:
         type: boolean
         description: Whether the service is an admin
+      roles:
+        type: array
+        description: The names of roles this service has
+        items:
+          type: string
       url:
         type: string
         description: The internal url where the service is running
@@ -862,6 +1016,11 @@ definitions:
       service:
         type: string
         description: The service that owns the token (undefined of owned by a user)
+      roles:
+        type: array
+        description: The names of roles this token has
+        items:
+          type: string
       note:
         type: string
         description: A note about the token, typically describing what it was created for.