mirror of
https://github.com/jupyterhub/jupyterhub.git
synced 2025-10-07 01:54:09 +00:00
2170 lines
69 KiB
YAML
2170 lines
69 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: JupyterHub REST API
|
||
description: |
|
||
The REST API for JupyterHub.
|
||
<a href="./">Return to JupyterHub documentation</a>.
|
||
license:
|
||
name: BSD-3-Clause
|
||
identifier: BSD-3-Clause
|
||
version: 5.4.0
|
||
servers:
|
||
- url: /hub/api
|
||
security:
|
||
- token: []
|
||
- oauth2: []
|
||
paths:
|
||
/:
|
||
get:
|
||
operationId: get-api
|
||
summary: Get JupyterHub version
|
||
description: |
|
||
This endpoint is not authenticated for the purpose of clients and user
|
||
to identify the JupyterHub version before setting up authentication.
|
||
responses:
|
||
200:
|
||
description: The JupyterHub version
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: string
|
||
description: The version of JupyterHub itself
|
||
/info:
|
||
get:
|
||
operationId: get-info
|
||
summary: Get detailed info about JupyterHub
|
||
description: |
|
||
Detailed JupyterHub information, including Python version,
|
||
JupyterHub's version and executable path,
|
||
and which Authenticator and Spawner are active.
|
||
responses:
|
||
200:
|
||
description: Detailed JupyterHub info
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: string
|
||
description: The version of JupyterHub itself
|
||
python:
|
||
type: string
|
||
description: The Python version, as returned by sys.version
|
||
sys_executable:
|
||
type: string
|
||
description: The path to sys.executable running JupyterHub
|
||
authenticator:
|
||
type: object
|
||
properties:
|
||
class:
|
||
type: string
|
||
description: The Python class currently active for
|
||
JupyterHub Authentication
|
||
version:
|
||
type: string
|
||
description: The version of the currently active
|
||
Authenticator
|
||
spawner:
|
||
type: object
|
||
properties:
|
||
class:
|
||
type: string
|
||
description: The Python class currently active for
|
||
spawning single-user notebook servers
|
||
version:
|
||
type: string
|
||
description: The version of the currently active Spawner
|
||
security:
|
||
- oauth2:
|
||
- read:hub
|
||
/user:
|
||
get:
|
||
operationId: get-current-user
|
||
summary: Get current user
|
||
description: |
|
||
Returns the User model for the owner of the authenticating token.
|
||
Includes information about the requesting token itself,
|
||
such as the currently authorized scopes.
|
||
responses:
|
||
200:
|
||
description: |
|
||
The authenticated user or service's model is returned
|
||
with additional information about the permissions associated with the request token.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/RequestIdentity"
|
||
security:
|
||
- oauth2: []
|
||
/users:
|
||
get:
|
||
operationId: get-users
|
||
summary: List users
|
||
parameters:
|
||
- name: state
|
||
in: query
|
||
description: |
|
||
Return only users who have servers in the given state.
|
||
If unspecified, return all users.
|
||
|
||
active: all users with any active servers (ready OR pending)
|
||
ready: all users who have any ready servers (running, not pending)
|
||
inactive: all users who have *no* active servers (complement of active)
|
||
|
||
Added in JupyterHub 1.3
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- inactive
|
||
- active
|
||
- ready
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
- name: include_stopped_servers
|
||
in: query
|
||
description: |
|
||
Include stopped servers in user model(s).
|
||
Added in JupyterHub 3.0.
|
||
Allows retrieval of information about stopped servers,
|
||
such as activity and state fields.
|
||
schema:
|
||
type: boolean
|
||
allowEmptyValue: true
|
||
- name: sort
|
||
in: query
|
||
description: |
|
||
Sort users by this key (new in JupyterHub 5.0).
|
||
Default: `id` (opaque but stable internal order).
|
||
Supported fields: `id`, `name`, `last_activity`.
|
||
Results will be in ascending order.
|
||
Descending order can be requested with a `-` prefix,
|
||
e.g. `sort=-last_activity` for most recently active users first.
|
||
schema:
|
||
type: string
|
||
examples:
|
||
default:
|
||
value: id
|
||
summary: |
|
||
default: sort by internal id
|
||
by_name:
|
||
value: name
|
||
summary: |
|
||
sort by user.name
|
||
recent_activity:
|
||
value: "-last_activity"
|
||
summary: |
|
||
sort by last activity, most recent first
|
||
responses:
|
||
200:
|
||
description: The Hub's user list
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/User"
|
||
security:
|
||
- oauth2:
|
||
- list:users
|
||
post:
|
||
operationId: post-users
|
||
summary: Create multiple users
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
usernames:
|
||
type: array
|
||
description: list of usernames to create on the Hub
|
||
items:
|
||
type: string
|
||
admin:
|
||
type: boolean
|
||
description: whether the created users should be admins
|
||
required: true
|
||
responses:
|
||
201:
|
||
description: The users have been created
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
description: The created users
|
||
items:
|
||
$ref: "#/components/schemas/User"
|
||
security:
|
||
- oauth2:
|
||
- admin:users
|
||
/users/{name}:
|
||
get:
|
||
operationId: get-user
|
||
summary: Get a user by name
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
- name: include_stopped_servers
|
||
in: query
|
||
description: Include stopped servers in user model(s).
|
||
schema:
|
||
type: boolean
|
||
allowEmptyValue: true
|
||
responses:
|
||
200:
|
||
description: The User model
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
security:
|
||
- oauth2:
|
||
- read:users
|
||
post:
|
||
operationId: post-user
|
||
summary: Create a single user
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
responses:
|
||
201:
|
||
description: The user has been created
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
security:
|
||
- oauth2:
|
||
- admin:users
|
||
delete:
|
||
operationId: delete-user
|
||
summary: Delete a user
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
responses:
|
||
204:
|
||
description: The user has been deleted
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- delete:users
|
||
patch:
|
||
operationId: patch-user
|
||
summary: Modify a user
|
||
description: Change a user's name or admin status
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
requestBody:
|
||
description: Updated user info. At least one key to be updated (name or
|
||
admin) is required.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: the new name (optional, if another key is updated
|
||
i.e. admin)
|
||
admin:
|
||
type: boolean
|
||
description: update admin (optional, if another key is updated
|
||
i.e. name)
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: The updated user info
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
security:
|
||
- oauth2:
|
||
- admin:users
|
||
/users/{name}/activity:
|
||
post:
|
||
operationId: post-user-activity
|
||
summary: Notify Hub of activity for a given user
|
||
description: Notify the Hub of activity by the user, e.g. accessing a
|
||
service or (more likely) actively using a server.
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
last_activity:
|
||
type: string
|
||
description: |
|
||
Timestamp of last-seen activity for this user.
|
||
Only needed if this is not activity associated
|
||
with using a given server.
|
||
format: date-time
|
||
servers:
|
||
type: object
|
||
properties:
|
||
<server name>:
|
||
required:
|
||
- last_activity
|
||
type: object
|
||
properties:
|
||
last_activity:
|
||
type: string
|
||
description: |
|
||
Timestamp of last-seen activity on this server.
|
||
format: date-time
|
||
description: |
|
||
Activity for a single server.
|
||
description: |
|
||
Register activity for specific servers by name.
|
||
The keys of this dict are the names of servers.
|
||
The default server has an empty name ('').
|
||
example:
|
||
last_activity: 2019-02-06T12:54:14Z
|
||
servers:
|
||
"":
|
||
last_activity: 2019-02-06T12:54:14Z
|
||
gpu:
|
||
last_activity: 2019-02-06T12:54:14Z
|
||
required: false
|
||
responses:
|
||
200:
|
||
description: Successfully updated activity
|
||
401:
|
||
description: Authentication/Authorization error
|
||
content: {}
|
||
404:
|
||
description: No such user
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- users:activity
|
||
/users/{name}/server:
|
||
post:
|
||
operationId: post-user-server
|
||
summary: Start a user's single-user notebook server
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
requestBody:
|
||
description: |
|
||
Spawn options can be passed as a JSON body
|
||
when spawning via the API instead of spawn form.
|
||
The structure of the options
|
||
will depend on the Spawner's configuration.
|
||
The body itself will be available as `user_options` for the
|
||
Spawner.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: false
|
||
responses:
|
||
201:
|
||
description: The user's notebook server has started
|
||
content: {}
|
||
202:
|
||
description: The user's notebook server has not yet started, but has
|
||
been requested
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- servers
|
||
|
||
delete:
|
||
operationId: delete-user-server
|
||
summary: Stop a user's server
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
responses:
|
||
202:
|
||
description: The user's notebook server has not yet stopped as it is
|
||
taking a while to stop
|
||
content: {}
|
||
204:
|
||
description: The user's notebook server has stopped
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- delete:servers
|
||
/users/{name}/servers/{server_name}:
|
||
post:
|
||
operationId: post-user-server-name
|
||
summary: Start a user's named server
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
- $ref: "#/components/parameters/serverName"
|
||
requestBody:
|
||
description: |
|
||
Spawn options can be passed as a JSON body
|
||
when spawning via the API instead of spawn form.
|
||
The structure of the options
|
||
will depend on the Spawner's configuration.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: false
|
||
responses:
|
||
201:
|
||
description: The user's notebook named-server has started
|
||
content: {}
|
||
202:
|
||
description: The user's notebook named-server has not yet started, but
|
||
has been requested
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- servers
|
||
delete:
|
||
operationId: delete-user-server-name
|
||
summary: Stop a user's named server
|
||
description: |
|
||
To remove the named server in addition to deleting it,
|
||
the body may be a JSON dictionary with a boolean `remove` field:
|
||
|
||
```json
|
||
{"remove": true}
|
||
```
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
- $ref: "#/components/parameters/serverName"
|
||
|
||
# FIXME: we probably shouldn't have request bodies on DELETE
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
remove:
|
||
type: boolean
|
||
description: |
|
||
Whether to fully remove the server, rather than just stop it.
|
||
Removing a server deletes things like the state of the stopped server.
|
||
Default: false.
|
||
required: false
|
||
responses:
|
||
202:
|
||
description: The user's notebook named-server has not yet stopped as
|
||
it is taking a while to stop
|
||
content: {}
|
||
204:
|
||
description: The user's notebook named-server has stopped
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- delete:servers
|
||
|
||
/users/{name}/shared:
|
||
get:
|
||
operationId: get-user-shared
|
||
summary: List servers shared with user
|
||
description: Returns list of Shares granting the user access to servers
|
||
owned by others (new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
|
||
responses:
|
||
200:
|
||
description: Shared access granted to the user
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/PaginatedList"
|
||
- type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ShareCode"
|
||
security:
|
||
- oauth2:
|
||
- read:users:shares
|
||
|
||
/users/{name}/shared/{owner}/{server_name}:
|
||
get:
|
||
operationId: get-user-shared-server
|
||
summary: |
|
||
Get user's shared access to server
|
||
description: |
|
||
Gets the Share representing a single user's access to a single server.
|
||
Users generally have access to this endpoint for themselves.
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
responses:
|
||
200:
|
||
description: The permissions granted to `user` on `owner/server`.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Share"
|
||
security:
|
||
- oauth2:
|
||
- read:users:shares
|
||
delete:
|
||
operationId: delete-user-shared-server
|
||
summary: |
|
||
Leave a shared server
|
||
description: |
|
||
Revokes a user's access to a shared server by deleting.
|
||
Users generally have access to this endpoint for themselves.
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
responses:
|
||
204:
|
||
description: |
|
||
Permission has been revoked,
|
||
the user no longer has access to the server.
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- users:shares
|
||
|
||
/users/{name}/tokens:
|
||
get:
|
||
operationId: get-user-tokens
|
||
summary: List tokens for the user
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
responses:
|
||
200:
|
||
description: The list of tokens
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
api_tokens:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Token"
|
||
401:
|
||
description: Authentication/Authorization error
|
||
content: {}
|
||
404:
|
||
description: No such user
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- read:tokens
|
||
post:
|
||
operationId: post-user-tokens
|
||
summary: Create a new token for the user
|
||
description: |
|
||
Creates a new token owned by the user.
|
||
Permissions can be limited by specifying a list of `scopes` in the JSON request body
|
||
(starting in JupyterHub 3.0; previously, permissions could be specified as `roles`,
|
||
which is deprecated in 3.0).
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
expires_in:
|
||
type: number
|
||
example: 3600
|
||
description: lifetime (in seconds) after which the requested
|
||
token will expire. Omit, or specify null or 0 for no
|
||
expiration.
|
||
note:
|
||
type: string
|
||
description: A note attached to the token for future
|
||
bookkeeping
|
||
roles:
|
||
type: array
|
||
description: |
|
||
A list of role names from which to derive scopes.
|
||
This is a shortcut for assigning collections of scopes;
|
||
Tokens do not retain role assignment.
|
||
(Changed in 3.0: roles are immediately resolved to scopes
|
||
instead of stored on roles.)
|
||
items:
|
||
type: string
|
||
scopes:
|
||
type: array
|
||
description: |
|
||
A list of scopes that the token should have.
|
||
(new in JupyterHub 3.0).
|
||
items:
|
||
type: string
|
||
required: false
|
||
responses:
|
||
201:
|
||
description: The newly created token
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/NewToken"
|
||
400:
|
||
description: Body must be a JSON dict or empty
|
||
content: {}
|
||
403:
|
||
description: Requested role does not exist
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- tokens
|
||
|
||
/users/{name}/tokens/{token_id}:
|
||
get:
|
||
operationId: get-user-token
|
||
summary: Get one token
|
||
description: Get the details for one token by id
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
- name: token_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: The info for the token
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Token"
|
||
security:
|
||
- oauth2:
|
||
- read:tokens
|
||
delete:
|
||
operationId: delete-user-token
|
||
summary: Delete (revoke) a token by id
|
||
parameters:
|
||
- $ref: "#/components/parameters/userName"
|
||
- name: token_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
204:
|
||
description: The token has been deleted
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- tokens
|
||
/groups:
|
||
get:
|
||
operationId: get-groups
|
||
summary: List groups
|
||
parameters:
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
responses:
|
||
200:
|
||
description: The list of groups
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- list:groups
|
||
/groups/{name}:
|
||
get:
|
||
operationId: get-group
|
||
summary: Get a group by name
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
responses:
|
||
200:
|
||
description: The group model
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- read:groups
|
||
post:
|
||
operationId: post-group
|
||
summary: Create a group
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
responses:
|
||
201:
|
||
description: The group has been created
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- admin:groups
|
||
delete:
|
||
operationId: delete-group
|
||
summary: Delete a group
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
responses:
|
||
204:
|
||
description: The group has been deleted
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- delete:groups
|
||
|
||
/groups/{name}/shared:
|
||
get:
|
||
operationId: get-group-shared
|
||
summary: List servers shared with group
|
||
description: |
|
||
Lists shares granting `group` access to shared servers
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
responses:
|
||
200:
|
||
description: Shared access granted to the group
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/PaginatedList"
|
||
- type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Share"
|
||
security:
|
||
- oauth2:
|
||
- read:groups:shares
|
||
|
||
/groups/{name}/shared/{owner}/{server_name}:
|
||
get:
|
||
operationId: get-group-shared-server
|
||
summary: Get group's shared access
|
||
description: |
|
||
Get the Share representing a single group's access to a single server
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
responses:
|
||
200:
|
||
description: The permissions granted to members of `group` on
|
||
`owner/server`
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Share"
|
||
security:
|
||
- oauth2:
|
||
- read:groups:shares
|
||
delete:
|
||
operationId: delete-group-shared-server
|
||
summary: Leave a share (group)
|
||
description: |
|
||
Leave a share by revoking a group's permissions on a single server
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
responses:
|
||
204:
|
||
description: |
|
||
Permission has been revoked,
|
||
the group members no longer have access to the server.
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- groups:shares
|
||
|
||
/groups/{name}/users:
|
||
post:
|
||
operationId: post-group-users
|
||
summary: Add users to a group
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
requestBody:
|
||
description: The users to add to the group
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
users:
|
||
type: array
|
||
description: List of usernames to add to the group
|
||
items:
|
||
type: string
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: The users have been added to the group
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- groups
|
||
delete:
|
||
operationId: delete-group-users
|
||
summary: |
|
||
Remove users from a group
|
||
description: |
|
||
Body should be a JSON dictionary
|
||
where `users` is a list of usernames to remove from the groups.
|
||
|
||
```json
|
||
{
|
||
"users": ["name1", "name2"]
|
||
}
|
||
```
|
||
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
requestBody:
|
||
description: The users to remove from the group
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
users:
|
||
type: array
|
||
description: List of usernames to remove from the group
|
||
items:
|
||
type: string
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: The users have been removed from the group
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- groups
|
||
|
||
/groups/{name}/properties:
|
||
put:
|
||
operationId: put-group-properties
|
||
summary: Set group properties
|
||
description: |
|
||
Set properties on a group
|
||
(new in 3.2)
|
||
parameters:
|
||
- $ref: "#/components/parameters/groupName"
|
||
requestBody:
|
||
description: The new group properties, as a JSON dict.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: |
|
||
The properties have been updated.
|
||
The updated group model is returned.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Group"
|
||
security:
|
||
- oauth2:
|
||
- groups
|
||
|
||
/shares/{owner}:
|
||
get:
|
||
operationId: get-shares-owner
|
||
summary: List shares by owner
|
||
description: |
|
||
List shares granting access to any of owner's servers
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
responses:
|
||
200:
|
||
description: The list of shares for any of the user's servers
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/PaginatedList"
|
||
- type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Share"
|
||
security:
|
||
- oauth2:
|
||
- read:shares
|
||
|
||
/shares/{owner}/{server_name}:
|
||
get:
|
||
operationId: get-shares-server
|
||
summary: List server shares
|
||
description: |
|
||
List shares granting access to a single server
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
responses:
|
||
200:
|
||
description: The list of shares granting access to the given server
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/PaginatedList"
|
||
- type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Share"
|
||
security:
|
||
- oauth2:
|
||
- read:shares
|
||
post:
|
||
operationId: post-shares-server
|
||
summary: Grant shared access
|
||
description: |
|
||
Grant shared access to a single server
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
requestBody:
|
||
description: The new group properties, as a JSON dict.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
# expires_in not implemented, for now at least
|
||
# expires_in:
|
||
# type: number
|
||
# description: |
|
||
# expiration in seconds.
|
||
# If unspecified, no expiration.
|
||
group:
|
||
type: string
|
||
description: |
|
||
group to grant permissions to.
|
||
Exactly one of 'user' and 'group' can be specified.
|
||
user:
|
||
type: string
|
||
description: |
|
||
user to grant permissions to.
|
||
Exactly one of 'user' and 'group' can be specified.
|
||
scopes:
|
||
type: array
|
||
description: scopes to grant
|
||
items:
|
||
type: string
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: The updated Share permissions
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Share"
|
||
security:
|
||
- oauth2:
|
||
- shares
|
||
- read:users:name
|
||
- read:groups:name
|
||
patch:
|
||
operationId: patch-shares-server
|
||
summary: Revoke shared access
|
||
description: |
|
||
Revoke shared access to a single server for a single user or group.
|
||
If scopes are specified, only the specified scopes are revoked,
|
||
allowing the target user or group to retain partial access.
|
||
Revocation is idempotent - revoking a scope not held does not result in an error.
|
||
The resulting Share model is returned if any scopes remain.
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
requestBody:
|
||
description: The share modifications to be made, as a JSON dict.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
group:
|
||
type: string
|
||
description: |
|
||
group to revoke permissions from.
|
||
Exactly one of 'user' and 'group' must be specified.
|
||
user:
|
||
type: string
|
||
description: |
|
||
user to revoke permissions from.
|
||
Exactly one of 'user' and 'group' must be specified.
|
||
scopes:
|
||
type: array
|
||
description: |
|
||
scopes to revoke.
|
||
If no scopes are specified, all permissions are revoked.
|
||
items:
|
||
type: string
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: |
|
||
The updated Share permissions.
|
||
An empty dict if no permissions remain.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Share"
|
||
security:
|
||
- oauth2:
|
||
- shares
|
||
- read:users:name
|
||
- read:groups:name
|
||
delete:
|
||
operationId: delete-shares-server
|
||
summary: Revoke all shared access
|
||
description: |
|
||
Revoke all shared access to a given server
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
responses:
|
||
204:
|
||
description: |
|
||
All shares for the server have been deleted
|
||
security:
|
||
- oauth2:
|
||
- shares
|
||
|
||
/share-codes/{owner}:
|
||
get:
|
||
operationId: get-share-codes-owner
|
||
summary: List share codes by owner
|
||
description: |
|
||
List share codes granting access to a user's servers
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
responses:
|
||
200:
|
||
description: The list of share codes
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/PaginatedList"
|
||
- type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ShareCode"
|
||
security:
|
||
- oauth2:
|
||
- read:shares
|
||
|
||
/share-codes/{owner}/{server_name}:
|
||
get:
|
||
operationId: get-share-codes-server
|
||
summary: List share codes
|
||
description: |
|
||
List share codes which can be exchanged for access to a single server
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
responses:
|
||
200:
|
||
description: The list of share codes
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/PaginatedList"
|
||
- type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/ShareCode"
|
||
security:
|
||
- oauth2:
|
||
- read:shares
|
||
post:
|
||
operationId: post-share-code
|
||
summary: Issue share code
|
||
description: |
|
||
Issue a share code, which can be exchanged for shared access to a single server
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
requestBody:
|
||
description: The new share code properties, as a JSON dict.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
expires_in:
|
||
type: number
|
||
description: |
|
||
expiration in seconds.
|
||
If unspecified, expires in one day (86400)
|
||
scopes:
|
||
type: array
|
||
description: scopes to grant
|
||
items:
|
||
type: string
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: |
|
||
The Share code you just created.
|
||
The code itself will be in the `code` field.
|
||
The code is not stored by JupyterHub and cannot be retrieved a second time.
|
||
`accept_url` will be the actual URL to share
|
||
(it will look like `/hub/accept-share?code=abc123`).
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: "#/components/schemas/ShareCode"
|
||
- type: object
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: The share code itself
|
||
example: abc123
|
||
accept_url:
|
||
type: string
|
||
description: The URL path for accepting the code
|
||
example: /hub/accept-share?code=abc123
|
||
full_accept_url:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The full URL for accepting the code,
|
||
if JupyterHub.public_url configuration is defined.
|
||
example:
|
||
https://hub.example.org/hub/accept-share?code=abc123
|
||
security:
|
||
- oauth2:
|
||
- shares
|
||
delete:
|
||
operationId: delete-share-code
|
||
summary: Revoke share code
|
||
description: |
|
||
Revoke a share code by id or code.
|
||
Exactly one of `id` or `code` must be specified.
|
||
(new in 5.0)
|
||
parameters:
|
||
- $ref: "#/components/parameters/sharedServerOwner"
|
||
- $ref: "#/components/parameters/sharedServerName"
|
||
- in: query
|
||
name: code
|
||
description: the share code to revoke
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: id
|
||
description: the id of the share code to revoke
|
||
schema:
|
||
type: string
|
||
responses:
|
||
204:
|
||
description: |
|
||
The share code has been revoked.
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- shares
|
||
|
||
/services:
|
||
get:
|
||
operationId: get-services
|
||
summary: List services
|
||
parameters:
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
responses:
|
||
200:
|
||
description: The service list
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/Service"
|
||
security:
|
||
- oauth2:
|
||
- read:services
|
||
/services/{name}:
|
||
get:
|
||
operationId: get-service
|
||
summary: Get a service by name
|
||
parameters:
|
||
- name: name
|
||
in: path
|
||
description: service name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: The Service model
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Service"
|
||
security:
|
||
- oauth2:
|
||
- read:services
|
||
/proxy:
|
||
get:
|
||
operationId: get-proxy
|
||
summary: Get the proxy's routing table
|
||
description: A convenience alias for getting the routing table directly
|
||
from the proxy
|
||
parameters:
|
||
- $ref: "#/components/parameters/paginationOffset"
|
||
- $ref: "#/components/parameters/paginationLimit"
|
||
responses:
|
||
200:
|
||
description: Routing table
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
description: configurable-http-proxy routing table (see
|
||
configurable-http-proxy docs for details)
|
||
security:
|
||
- oauth2:
|
||
- proxy
|
||
post:
|
||
operationId: post-proxy
|
||
summary: Force the Hub to sync with the proxy
|
||
responses:
|
||
200:
|
||
description: Success
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- proxy
|
||
patch:
|
||
operationId: patch-proxy
|
||
summary: Notify the Hub about a new proxy
|
||
description: Notifies the Hub of a new proxy to use.
|
||
requestBody:
|
||
description: Any values that have changed for the new proxy. All keys
|
||
are optional.
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
ip:
|
||
type: string
|
||
description: IP address of the new proxy
|
||
port:
|
||
type: string
|
||
description: Port of the new proxy
|
||
protocol:
|
||
type: string
|
||
description: Protocol of new proxy, if changed
|
||
auth_token:
|
||
type: string
|
||
description: CONFIGPROXY_AUTH_TOKEN for the new proxy
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: Success
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- proxy
|
||
/authorizations/token:
|
||
post:
|
||
deprecated: true
|
||
operationId: post-auth-token
|
||
summary: Request a new API token
|
||
description: |
|
||
Request a new API token to use with the JupyterHub REST API.
|
||
If not already authenticated, username and password can be sent
|
||
in the JSON request body.
|
||
Logging in via this method is only available when the active Authenticator
|
||
accepts passwords (e.g. not OAuth).
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
username:
|
||
type: string
|
||
password:
|
||
type: string
|
||
required: false
|
||
responses:
|
||
200:
|
||
description: The new API token
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
token:
|
||
type: string
|
||
description: The new API token.
|
||
403:
|
||
description: The user can not be authenticated.
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- tokens
|
||
|
||
/authorizations/token/{token}:
|
||
get:
|
||
deprecated: true
|
||
operationId: get-auth-token
|
||
summary: Identify a user or service from an API token
|
||
parameters:
|
||
- name: token
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: The user or service identified by the API token
|
||
content: {}
|
||
404:
|
||
description: A user or service is not found.
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- (no_scope)
|
||
/authorizations/cookie/{cookie_name}/{cookie_value}:
|
||
get:
|
||
operationId: get-auth-cookie
|
||
summary: Identify a user from a cookie
|
||
description: Used by single-user notebook servers to hand off cookie
|
||
authentication to the Hub
|
||
parameters:
|
||
- name: cookie_name
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: cookie_value
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: The user identified by the cookie
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/User"
|
||
404:
|
||
description: A user is not found.
|
||
content: {}
|
||
deprecated: true
|
||
/oauth2/authorize:
|
||
get:
|
||
operationId: get-oauth-authorize
|
||
summary: OAuth 2.0 authorize endpoint
|
||
description: |
|
||
Redirect users to this URL to begin the OAuth process.
|
||
It is not an API endpoint.
|
||
parameters:
|
||
- name: client_id
|
||
in: query
|
||
description: The client id
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: response_type
|
||
in: query
|
||
description: The response type (always 'code')
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: state
|
||
in: query
|
||
description: A state string
|
||
schema:
|
||
type: string
|
||
- name: redirect_uri
|
||
in: query
|
||
description: The redirect url
|
||
required: true
|
||
schema:
|
||
type: string
|
||
responses:
|
||
200:
|
||
description: Success
|
||
content: {}
|
||
400:
|
||
description: OAuth2Error
|
||
content: {}
|
||
/oauth2/token:
|
||
post:
|
||
operationId: post-oauth-token
|
||
summary: Request an OAuth2 token
|
||
description: |
|
||
Request an OAuth2 token from an authorization code.
|
||
This request completes the OAuth process.
|
||
requestBody:
|
||
content:
|
||
application/x-www-form-urlencoded:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- client_id
|
||
- client_secret
|
||
- code
|
||
- grant_type
|
||
- redirect_uri
|
||
properties:
|
||
client_id:
|
||
type: string
|
||
description: The client id
|
||
client_secret:
|
||
type: string
|
||
description: The client secret
|
||
grant_type:
|
||
type: string
|
||
description: The grant type (always 'authorization_code')
|
||
enum:
|
||
- authorization_code
|
||
code:
|
||
type: string
|
||
description: The code provided by the authorization redirect
|
||
redirect_uri:
|
||
type: string
|
||
description: The redirect url
|
||
required: true
|
||
responses:
|
||
200:
|
||
description: JSON response including the token
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
access_token:
|
||
type: string
|
||
description: The new API token for the user
|
||
token_type:
|
||
type: string
|
||
description: Will always be 'Bearer'
|
||
/shutdown:
|
||
post:
|
||
operationId: post-shutdown
|
||
summary: Shutdown the Hub
|
||
requestBody:
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
proxy:
|
||
type: boolean
|
||
description: Whether the proxy should be shutdown as well
|
||
(default from Hub config)
|
||
servers:
|
||
type: boolean
|
||
description: Whether users' notebook servers should be
|
||
shutdown as well (default from Hub config)
|
||
required: false
|
||
responses:
|
||
202:
|
||
description: Shutdown successful
|
||
content: {}
|
||
400:
|
||
description: Unexpected value for proxy or servers
|
||
content: {}
|
||
security:
|
||
- oauth2:
|
||
- shutdown
|
||
|
||
components:
|
||
parameters:
|
||
userName:
|
||
name: name
|
||
in: path
|
||
description: username
|
||
required: true
|
||
schema:
|
||
type: string
|
||
groupName:
|
||
name: name
|
||
in: path
|
||
description: group name
|
||
required: true
|
||
schema:
|
||
type: string
|
||
serverName:
|
||
name: server_name
|
||
in: path
|
||
description: |
|
||
name given to a named-server (empty string for default server).
|
||
|
||
Note that depending on your JupyterHub infrastructure there are limitations to `server_name`. Default spawner with K8s pod will not allow Jupyter Notebooks to be spawned with a name that contains more than 253 characters (keep in mind that the pod will be spawned with extra characters to identify the user and hub).
|
||
required: true
|
||
schema:
|
||
type: string
|
||
paginationOffset:
|
||
name: offset
|
||
in: query
|
||
description: |
|
||
Return a number of results, starting at the specified offset.
|
||
Can be used with limit to paginate.
|
||
If unspecified, return all items.
|
||
required: false
|
||
schema:
|
||
type: number
|
||
paginationLimit:
|
||
name: limit
|
||
in: query
|
||
description: |
|
||
Return a finite number of results.
|
||
Can be used with offset to paginate.
|
||
If unspecified, use api_page_default_limit.
|
||
required: false
|
||
schema:
|
||
type: number
|
||
sharedServerOwner:
|
||
name: owner
|
||
in: path
|
||
description: name of the user who owns the shared server
|
||
required: true
|
||
schema:
|
||
type: string
|
||
sharedServerName:
|
||
name: server_name
|
||
in: path
|
||
description: |
|
||
name of the shared server
|
||
(empty string for default server, which means the URL ends with a trailing '/', e.g. `/username/`).
|
||
required: true
|
||
schema:
|
||
type: string
|
||
|
||
schemas:
|
||
Pagination:
|
||
type: object
|
||
description: page info for paginated endpoints
|
||
properties:
|
||
total:
|
||
type: number
|
||
description: total number of results for the query
|
||
limit:
|
||
type: number
|
||
description: the maximum number of results
|
||
offset:
|
||
type: number
|
||
description: the starting point for this
|
||
next:
|
||
description: |
|
||
fields for the next page, if any.
|
||
Null if this is the last page.
|
||
type:
|
||
- object
|
||
- "null"
|
||
properties:
|
||
offset:
|
||
type: number
|
||
description: the offset for the next page
|
||
limit:
|
||
type: number
|
||
description: the same as the above limit, for consistency
|
||
url:
|
||
type: string
|
||
description: |
|
||
the assembled url for the next page,
|
||
with query parameters already included.
|
||
PaginatedList:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
type: object
|
||
_pagination:
|
||
$ref: "#/components/schemas/Pagination"
|
||
User:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The user's name
|
||
kind:
|
||
type: string
|
||
description: the string 'user' to distinguish from 'service'
|
||
enum:
|
||
- user
|
||
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
|
||
items:
|
||
type: string
|
||
server:
|
||
type: string
|
||
description: The user's notebook server's base URL, if running; null
|
||
if not.
|
||
pending:
|
||
type: string
|
||
description: The currently pending action, if any
|
||
enum:
|
||
- spawn
|
||
- stop
|
||
last_activity:
|
||
type: string
|
||
description: Timestamp of last-seen activity from the user
|
||
format: date-time
|
||
servers:
|
||
type: object
|
||
description: |
|
||
The servers for this user.
|
||
By default: only includes _active_ servers.
|
||
Changed in 3.0: if `?include_stopped_servers` parameter is specified,
|
||
stopped servers will be included as well.
|
||
additionalProperties:
|
||
$ref: "#/components/schemas/Server"
|
||
auth_state:
|
||
type: object
|
||
properties: {}
|
||
description: |
|
||
Authentication state of the user. Only available with admin:users:auth_state
|
||
scope. None otherwise.
|
||
Server:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The server's name. The user's default server has an empty
|
||
name ('')
|
||
ready:
|
||
type: boolean
|
||
description: |
|
||
Whether the server is ready for traffic.
|
||
Will always be false when any transition is pending.
|
||
stopped:
|
||
type: boolean
|
||
description: |
|
||
Whether the server is stopped. Added in JupyterHub 3.0,
|
||
and only useful when using the `?include_stopped_servers`
|
||
request parameter.
|
||
Now that stopped servers may be included (since JupyterHub 3.0),
|
||
this is the simplest way to select stopped servers.
|
||
Always equivalent to `not (ready or pending)`.
|
||
pending:
|
||
type: string
|
||
description: |
|
||
The currently pending action, if any.
|
||
A server is not ready if an action is pending.
|
||
enum:
|
||
- spawn
|
||
- stop
|
||
url:
|
||
type: string
|
||
description: |
|
||
The URL path where the server can be accessed
|
||
(typically /user/:name/:server.name/).
|
||
Will be a full URL if subdomains are configured.
|
||
progress_url:
|
||
type: string
|
||
description: |
|
||
The URL path for an event-stream to retrieve events during a spawn.
|
||
full_url:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The full URL of the server (`https://hub.example.org/user/:name/:servername`).
|
||
`null` unless JupyterHub.public_url or subdomains are configured.
|
||
|
||
Added in 5.0.
|
||
full_progress_url:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The full URL for the progress events (`https://hub.example.org/hub/api/users/:name/servers/:servername/progress`).
|
||
`null` unless JupyterHub.public_url is configured.
|
||
|
||
Added in 5.0.
|
||
started:
|
||
type: string
|
||
description: UTC timestamp when the server was last started.
|
||
format: date-time
|
||
last_activity:
|
||
type: string
|
||
description: UTC timestamp last-seen activity on this server.
|
||
format: date-time
|
||
state:
|
||
type: object
|
||
properties: {}
|
||
description: Arbitrary internal state from this server's spawner. Only
|
||
available on the hub's users list or get-user-by-name method, and
|
||
only with admin:users:server_state scope. None otherwise.
|
||
user_options:
|
||
type: object
|
||
properties: {}
|
||
description: User specified options for the user's spawned instance of
|
||
a single-user server.
|
||
RequestIdentity:
|
||
description: |
|
||
The model for the entity making the request.
|
||
Extends User or Service model to add information about the specific credentials (e.g. session or token-authorised scopes).
|
||
allOf:
|
||
- type: object
|
||
oneOf:
|
||
- $ref: "#/components/schemas/User"
|
||
- $ref: "#/components/schemas/Service"
|
||
discriminator:
|
||
propertyName: kind
|
||
mapping:
|
||
user: "#/components/schemas/User"
|
||
service: "#/components/schemas/Service"
|
||
- type: object
|
||
properties:
|
||
kind:
|
||
type: string
|
||
description: |
|
||
'user' or 'service' depending on the entity which owns the token
|
||
enum:
|
||
- user
|
||
- service
|
||
session_id:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The session id associated with the request's OAuth token, if any.
|
||
null, if the request token not associated with a session id.
|
||
|
||
Added in 2.0.
|
||
scopes:
|
||
type: array
|
||
description: |
|
||
The list of all expanded scopes the request credentials have access to.
|
||
|
||
Added in 2.0.
|
||
items:
|
||
type: string
|
||
example:
|
||
- "read:users"
|
||
- "access:servers!user=name"
|
||
token_id:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The id of the token authorizing the request, if any.
|
||
This id can be used to revoke the token via the API.
|
||
Null if the request is not authorized with a token.
|
||
|
||
Added in 5.0.
|
||
Group:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The group's name
|
||
kind:
|
||
type: string
|
||
description: Always the string 'group'
|
||
enum:
|
||
- group
|
||
users:
|
||
type: array
|
||
description: The names of users who are members of this group
|
||
items:
|
||
type: string
|
||
properties:
|
||
type: object
|
||
description: |
|
||
Group properties (a dictionary).
|
||
|
||
Unused by JupyterHub itself,
|
||
but an extension point to store information about groups.
|
||
|
||
Added in JupyterHub 3.2.
|
||
roles:
|
||
type: array
|
||
description: The names of roles this group has
|
||
items:
|
||
type: string
|
||
Service:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description: The service's name
|
||
kind:
|
||
type: string
|
||
description: the string 'service' to distinguish from 'user'
|
||
enum:
|
||
- service
|
||
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
|
||
prefix:
|
||
type: string
|
||
description: The proxied URL prefix to the service's url
|
||
pid:
|
||
type: number
|
||
description: The PID of the service process (if managed)
|
||
command:
|
||
type: array
|
||
description: The command used to start the service (if managed)
|
||
items:
|
||
type: string
|
||
info:
|
||
type: object
|
||
properties: {}
|
||
description: |
|
||
Additional information a deployment can attach to a service.
|
||
JupyterHub does not use this field.
|
||
|
||
SharedServer:
|
||
description: Subset of Server model present in Share responses
|
||
type: object
|
||
properties:
|
||
# these are the minimal subset of a server model needed for access
|
||
# e.g. where is it (name, url), whose is it (user.name), and is it running (ready)
|
||
name:
|
||
type: string
|
||
description: the server name. '' for the default server.
|
||
url:
|
||
type: string
|
||
description: the server's URL (path only when not using subdomains)
|
||
full_url:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The full URL of the server (`https://hub.example.org/user/:name/:servername`).
|
||
`null` unless JupyterHub.public_url or subdomains are configured.
|
||
ready:
|
||
type: boolean
|
||
description: whether the server is ready
|
||
user:
|
||
type: object
|
||
description: the server's owner
|
||
properties:
|
||
name:
|
||
type: string
|
||
|
||
Share:
|
||
description: |
|
||
A single sharing permission.
|
||
There is at most one of these objects per (server, user) or (server, group) combination.
|
||
type: object
|
||
properties:
|
||
server:
|
||
description: the server granting shared access
|
||
$ref: "#/components/schemas/SharedServer"
|
||
scopes:
|
||
description: the scopes granted by this Share
|
||
type: array
|
||
items:
|
||
type: string
|
||
group:
|
||
description: the group being shared with (exactly one of 'user' or
|
||
'group' will be non-null, the other will be null)
|
||
type:
|
||
- object
|
||
- "null"
|
||
properties:
|
||
name:
|
||
type: string
|
||
user:
|
||
description: the user being shared with (exactly one of 'user' or
|
||
'group' will be non-null, the other will be null)
|
||
type:
|
||
- object
|
||
- "null"
|
||
properties:
|
||
name:
|
||
type: string
|
||
created_at:
|
||
description: when the share was first granted
|
||
type: string
|
||
format: date-time
|
||
|
||
ShareCode:
|
||
description: A single sharing code. There is at most one of these objects
|
||
per (server, user) or (server, group) combination.
|
||
type: object
|
||
properties:
|
||
server:
|
||
description: the server granting shared access
|
||
$ref: "#/components/schemas/SharedServer"
|
||
scopes:
|
||
description: the scopes granted by this Share
|
||
type: array
|
||
items:
|
||
type: string
|
||
id:
|
||
type: string
|
||
description: |
|
||
the share-code's id.
|
||
Can be used to revoke share codes.
|
||
created_at:
|
||
description: when the share code was issued
|
||
type: string
|
||
format: date-time
|
||
expires_at:
|
||
description: |
|
||
When the share code will expire,
|
||
always in the future.
|
||
`null` if the code does not expire.
|
||
type:
|
||
- string
|
||
- "null"
|
||
format: date-time
|
||
|
||
Token:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: The id of the API token. Used for modifying or deleting
|
||
the token.
|
||
user:
|
||
type: string
|
||
description: The user that owns a token (undefined if owned by a
|
||
service)
|
||
service:
|
||
type: string
|
||
description: The service that owns the token (undefined of owned by a
|
||
user)
|
||
roles:
|
||
type: array
|
||
description: Deprecated in JupyterHub 3, always an empty list. Tokens
|
||
have 'scopes' starting from JupyterHub 3.
|
||
items:
|
||
type: string
|
||
scopes:
|
||
type: array
|
||
description: List of scopes this token has been assigned. New in
|
||
JupyterHub 3. In JupyterHub 2.x, tokens were assigned 'roles'
|
||
instead of scopes.
|
||
items:
|
||
type: string
|
||
note:
|
||
type: string
|
||
description: A note about the token, typically describing what it was
|
||
created for.
|
||
created:
|
||
type: string
|
||
description: Timestamp when this token was created
|
||
format: date-time
|
||
expires_at:
|
||
type: string
|
||
description: Timestamp when this token expires. Null if there is no
|
||
expiry.
|
||
format: date-time
|
||
last_activity:
|
||
type: string
|
||
description: |
|
||
Timestamp of last-seen activity using this token.
|
||
Can be null if token has never been used.
|
||
format: date-time
|
||
session_id:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The session id associated with the token, if any.
|
||
Only used for tokens set during oauth flows.
|
||
|
||
Added in 2.0.
|
||
|
||
NewToken:
|
||
type: object
|
||
properties:
|
||
token:
|
||
type: string
|
||
description: The token itself. Only present in responses to requests
|
||
for a new token.
|
||
id:
|
||
type: string
|
||
description: The id of the API token. Used for modifying or deleting
|
||
the token.
|
||
user:
|
||
type: string
|
||
description: The user that owns a token (undefined if owned by a
|
||
service)
|
||
service:
|
||
type: string
|
||
description: The service that owns the token (undefined of owned by a
|
||
user)
|
||
roles:
|
||
type: array
|
||
description: Deprecated in JupyterHub 3, always an empty list. Tokens
|
||
have 'scopes' starting from JupyterHub 3.
|
||
items:
|
||
type: string
|
||
scopes:
|
||
type: array
|
||
description: List of scopes this token has been assigned. New in
|
||
JupyterHub 3. In JupyterHub 2.x, tokens were assigned 'roles'
|
||
instead of scopes.
|
||
items:
|
||
type: string
|
||
note:
|
||
type: string
|
||
description: A note about the token, typically describing what it was
|
||
created for.
|
||
created:
|
||
type: string
|
||
description: Timestamp when this token was created
|
||
format: date-time
|
||
expires_at:
|
||
type: string
|
||
description: Timestamp when this token expires. Null if there is no
|
||
expiry.
|
||
format: date-time
|
||
last_activity:
|
||
type: string
|
||
description: |
|
||
Timestamp of last-seen activity using this token.
|
||
Can be null if token has never been used.
|
||
format: date-time
|
||
session_id:
|
||
type:
|
||
- string
|
||
- "null"
|
||
description: |
|
||
The session id associated with the token, if any.
|
||
Only used for tokens set during oauth flows.
|
||
|
||
Added in 2.0.
|
||
|
||
securitySchemes:
|
||
token:
|
||
type: http
|
||
scheme: bearer
|
||
oauth2:
|
||
type: oauth2
|
||
flows:
|
||
authorizationCode:
|
||
authorizationUrl: /hub/api/oauth2/authorize
|
||
tokenUrl: /hub/api/oauth2/token
|
||
scopes:
|
||
(no_scope): Identify the owner of the requesting entity.
|
||
self: The user’s own resources _(metascope for users, resolves to
|
||
(no_scope) for services)_
|
||
inherit: Everything that the token-owning entity can access
|
||
_(metascope for tokens)_
|
||
admin-ui: Access the admin page. Permission to take actions via the
|
||
admin page granted separately.
|
||
admin:users: Read, modify, create, and delete users and their
|
||
authentication state, not including their servers or tokens. This
|
||
is an extremely privileged scope and should be considered
|
||
tantamount to superuser.
|
||
admin:auth_state: Read a user’s authentication state.
|
||
users: Read and write permissions to user models (excluding servers,
|
||
tokens and authentication state).
|
||
delete:users: Delete users.
|
||
list:users: List users, including at least their names.
|
||
read:users: Read user models (including the URL of the default
|
||
server if it is running).
|
||
read:users:name: Read names of users.
|
||
read:users:groups: Read users’ group membership.
|
||
read:users:activity: Read time of last user activity.
|
||
read:roles: Read role assignments.
|
||
read:roles:users: Read user role assignments.
|
||
read:roles:services: Read service role assignments.
|
||
read:roles:groups: Read group role assignments.
|
||
users:activity: Update time of last user activity.
|
||
admin:servers: Read, start, stop, create and delete user servers and
|
||
their state.
|
||
admin:server_state: Read and write users’ server state.
|
||
servers: Start and stop user servers.
|
||
read:servers: Read users’ names and their server models (excluding
|
||
the server state).
|
||
delete:servers: Stop and delete users' servers.
|
||
tokens: Read, write, create and delete user tokens.
|
||
read:tokens: Read user tokens.
|
||
admin:groups: Read and write group information, create and delete
|
||
groups.
|
||
groups: 'Read and write group information, including adding/removing any
|
||
users to/from groups. Note: adding users to groups may affect permissions.'
|
||
list:groups: List groups, including at least their names.
|
||
read:groups: Read group models.
|
||
read:groups:name: Read group names.
|
||
delete:groups: Delete groups.
|
||
admin:services: Create, read, update, delete services, not including
|
||
services defined from config files.
|
||
list:services: List services, including at least their names.
|
||
read:services: Read service models.
|
||
read:services:name: Read service names.
|
||
read:hub: Read detailed information about the Hub.
|
||
access:servers: Access user servers via API or browser.
|
||
access:services: Access services via API or browser.
|
||
users:shares: Read and revoke a user's access to shared servers.
|
||
read:users:shares: Read servers shared with a user.
|
||
groups:shares: Read and revoke a group's access to shared servers.
|
||
read:groups:shares: Read servers shared with a group.
|
||
read:shares: Read information about shared access to servers.
|
||
shares: Manage access to shared servers.
|
||
proxy: Read information about the proxy’s routing table, sync the
|
||
Hub with the proxy and notify the Hub about a new proxy.
|
||
shutdown: Shutdown the hub.
|
||
read:metrics: Read prometheus metrics.
|