jupyterhub/docs/source/api/rest.md

The JupyterHub REST API

Using the JupyterHub REST API, you can perform actions on the Hub, such as:

• checking which users are active
• adding or removing users
• stopping or starting single user notebook servers

API tokens

Create an API token

To send requests using JupyterHub API, you must pass an API token with the request. You can create a token for an individual user using the following command:

jupyterhub token USERNAME

Adding API tokens to the hub's configuration

You may also add a dictionary of API tokens and usernames to the hub's configurations file, jupyterhub_config.py:

c.JupyterHub.api_tokens = {
    'secret-token': 'username',
}

Making an API request

To authenticate your requests, pass the API token in the request's Authorization header.

Example: List the hub's users

Using the popular Python requests library, the following code sends an API request and an API token for authorization:

import requests

api_url = 'http://127.0.0.1:8081/hub/api'

r = requests.get(api_url + '/users', 
    headers={
             'Authorization': 'token %s' % token,
            }
    )

r.raise_for_status()
users = r.json()

You can see the full REST API Spec for details. The same REST API Spec can be viewed in a more visually appealing style on swagger's petstore. Both resources contain the same information and differ only in its display.