---
tags: jupyterhub
---

# JupyterHub OAuth scopes

**Basic design:**

- `resource` scope, such as `users` or `groups` provides 'default' read/write permissions to everything below that (e.g. `users:servers` scope is included within the `users` scope)
- `admin:resource` extends permissions beyond default where appropriate, e.g. creating/deleting users or groups
- `resource:subresource` provides more specific access, always limiting from default
- `read:resource` or `read:resource:subresource` limits permissions to read-only operations on the same resources
- single filter after `!` (e.g. `resource!user=username`) limits matches based on user/group/server (only one per scope, issue scope multiple times for multiple subsets, e.g. one group from groups + specific users)
- `!server=servername` filter implies limiting to token-owning user

## Available scopes

| Scope | Description / [API endpoints](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/) |
|:-------------- | --------------------------------------------------------- |
| `all` | Grants access to everything the user (token owner) can do <br> **{name} in below API endpoints must correspond to the user's username** <br> [GET /user](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_user) <br> [GET /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name_) <br> [GET /users/{name}/tokens](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name__tokens) <br> [POST /users/{name}/tokens](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__tokens) <br> [GET /users/{name}/tokens/{token_id}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name__tokens__token_id_) <br> [DELETE /users/{name}/tokens/{token_id}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__tokens__token_id_) <br> [POST /users/{name}/activity](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__activity) <br> [POST /users/{name}/server](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__server) <br> [DELETE /users/{name}/server](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__server) <br> [POST /users/{name}/server/{server_name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__servers__server_name_) <br> [DELETE /users/{name}/server/{server_name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__servers__server_name_)|
| &nbsp;&nbsp;&nbsp;`read:all` | Read-only access to everything the user can read (including the whoami identifier) <br> **{name} in below API endpoints must correspond to the user's username** <br> [GET /user](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_user) <br> [GET /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name_) <br> [GET /users/{name}/tokens](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name__tokens) <br> [POST /users/{name}/tokens](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__tokens) <br> [GET /users/{name}/tokens/{token_id}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name__tokens__token_id_) <br> [DELETE /users/{name}/tokens/{token_id}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__tokens__token_id_) |
| `users` | Grants access to managing users including reading users' model, posting activity and starting/stoping users servers. **Does not include** creating/removing users and their servers or tokens. <br> [GET /users](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users) <br> [GET /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name_) <br> [PATCH /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/patch_users__name_) <br> [POST /users/{name}/activity](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__activity) <br> [POST /users/{name}/server](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__server) <br> [DELETE /users/{name}/server](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__server) <br> [POST /users/{name}/server/{server_name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__servers__server_name_) <br> [DELETE /users/{name}/server/{server_name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__servers__server_name_) |
| &nbsp;&nbsp;&nbsp;`read:users` | Read-only access to users' models <br> [GET /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name_) <br> [GET /users](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users) |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`read:users!user=username` | Read-only access to a single user's model <br> [GET /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name_) |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`read:users:name` | Read-only access to users' names |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`read:users:groups` | Read-only access to users' groups |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`read:users:activity` | Read-only access to users' activity |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`read:users:activity!group=groupname` | Limits the above to only a specific group's users' activity |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`read:users:servers` | Read-only access to users' servers |
|&nbsp;&nbsp;&nbsp;`users:activity!user=username` | Allows to update a user's activity <br> [POST /users/{name}/activity](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__activity) |
| &nbsp;&nbsp;&nbsp;`users:servers` | Allows to start/stop any server <br> [POST /users/{name}/server](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__server) <br> [DELETE /users/{name}/server](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__server) |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`users:servers!server=servername` | Limits the above access to a single server <br> [POST /users/{name}/server/{server_name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__servers__server_name_) <br> [DELETE /users/{name}/server/{server_name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__servers__server_name_) |
|`users:tokens` | Grants access to users' tokens and allows to create/revoke tokens, **not included in the `users` scope** <br> [GET /users/{name}/tokens](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name__tokens) <br> [POST /users/{name}/tokens](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name__tokens) <br> [GET /users/{name}/tokens/{token_id}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_users__name__tokens__token_id_) <br> [DELETE /users/{name}/tokens/{token_id}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name__tokens__token_id_) <br> [GET /authorizations/token/{token}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_authorizations_token__token_) <br> [POST /authorizations/token](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_authorizations_token) |
| &nbsp;&nbsp;&nbsp;`read:users:tokens` | Allows only to identify a user from a token <br> [GET /authorizations/token/{token}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_authorizations_token__token_) |
|`admin:users` | Grants permission to create multiple users and create/delete a single user <br> [POST /users](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users) <br> [POST /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_users__name_) <br> [DELETE /users/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_users__name_) |
| `admin:users:servers` | Grants permission to create/remove users' servers |
| `groups` | Grants access to add/remove users from any group <br> [GET /groups](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_groups) <br> [GET /groups/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_groups__name_) <br> [POST /groups/{name}/users](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_groups__name__users) <br> [DELETE /groups/{name}/users](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_groups__name__users) |
| &nbsp;&nbsp;&nbsp;`groups!group=groupname` | Limits the above to add/remove users from a specific group <br> [GET /groups/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_groups__name_)<br> [POST /groups/{name}/users](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_groups__name__users) <br> [DELETE /groups/{name}/users](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_groups__name__users) |
| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`read:groups` | Read-only access to groups <br> [GET /groups](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_groups) <br> [GET /groups/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_groups__name_) |
| `admin:groups` | Allows to create/delete groups <br> [POST /groups/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_groups__name_) <br> [DELETE /groups/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/delete_groups__name_) |
|`read:services` | Read-only access to services <br> [GET /services](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_services) <br> [GET /services/{name}](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_services__name_) |
|`read:hub` | Read-only access to detailed information about JupyterHub <br> [GET /info](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_info) |
| `proxy` | Grants access to get the proxy’s routing table, force the Hub to sync the proxy & notify the Hub about the new proxy <br> [GET /proxy](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/get_proxy) <br> [POST /proxy](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_proxy) <br> [PATCH /proxy](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/patch_proxy) |
| `shutdown` | Grants permission to shut down the Hub <br> [POST /shutdown](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#/default/post_shutdown) |
| | |

**Example use cases**
- user scripting their own access
1. view, manage all their own servers
`all`
- cull-idle-servers wants:
1. get servers and their activity
2. shutdown servers
3. (optional) delete users
`users:servers` + `admin:servers`
- api-launcher
1. create users
2. create new servers
3. start and stop servers
4. delete users
`admin:users` + `admin:servers` + `users:servers`
- oauth client (services, single-user servers default)
1. update last_activity
2. issue tokens with limited scope (is this a scope or is it part of oauth?)
3. issued tokens should have only 'identify' scope
4. check validity of cookies and tokens
`users:activity!user=username` + `users:tokens`