Reorder token request docs

- suggest token page first
- remove caveat about JupyterHub 0.8, which can be assumed now
- undocument `jupyterhub token`
- refresh token page screenshots, and remove duplicate screenshot of the token page
- minor improvements to language in token page

docs/source/howto/rest.md

@@ -33,36 +33,13 @@ such as:
 To send requests using the JupyterHub API, you must pass an API token with
 the request.
 
-The preferred way of generating an API token is by running:
+While JupyterHub is running, any JupyterHub user can request a token via the `token` page.
-
+This is accessible via a `token` link in the top nav bar from the JupyterHub home page,
-```bash
+or at the URL `/hub/token`.
-openssl rand -hex 32
-```
-
-This `openssl` command generates a potential token that can then be
-added to JupyterHub using `.api_tokens` configuration setting in
-`jupyterhub_config.py`.
-
-```{note}
-The api_tokens configuration has been softly deprecated since the introduction of services.
-```
-
-Alternatively, you can use the `jupyterhub token` command to generate a token
-for a specific hub user by passing the **username**:
-
-```bash
-jupyterhub token <username>
-```
-
-This command generates a random string to use as a token and registers
-it for the given user with the Hub's database.
-
-In [version 0.8.0](changelog), a token request page for
-generating an API token is available from the JupyterHub user interface:
 
 :::{figure-md}
 
-![token request page](../images/token-request.png)
+![token request page](../images/token-page.png)
 
 JupyterHub's API token page
 :::
@@ -74,6 +51,40 @@ JupyterHub's token page after successfully requesting a token.
 
 :::
 
+### Register API tokens via configuration
+
+Sometimes, you'll want to pre-generate a token for access to JupyterHub,
+typically for use by external services,
+so that both JupyterHub and the service have access to the same value.
+
+First, you need to generate a good random secret.
+A good way of generating an API token is by running:
+
+```bash
+openssl rand -hex 32
+```
+
+This `openssl` command generates a potential token that can then be added to JupyterHub configuration in `jupyterhub_config.py`.
+
+For external services, this would be registered with JupyterHub via configuration:
+
+```python
+c.JupyterHub.services = [
+    {
+        "name": "my-service",
+        "api_token": the_secret_value,
+    },
+]
+```
+
+At this point, requests authenticated with the token will be associated with The service `my-service`.
+
+```{note}
+You can also load additional tokens for users via the `JupyterHub.api_tokens` configuration.
+
+However, this option has been softly deprecated since the introduction of services.
+```
+
 ## Assigning permissions to a token
 
 Prior to JupyterHub 2.0, there were two levels of permissions:

docs/source/tutorial/getting-started/services-basics.md

@@ -39,7 +39,7 @@ openssl rand -hex 32
 In [version 0.8.0](changelog), a TOKEN request page for
 generating an API token is available from the JupyterHub user interface:
 
-![Request API TOKEN page](/images/token-request.png)
+![Request API TOKEN page](/images/token-page.png)
 
 ![API TOKEN success page](/images/token-request-success.png)
 

share/jupyterhub/templates/token.html

@@ -21,7 +21,7 @@
           This note will help you keep track of what your tokens are for.
         </small>
         <br><br>
-        <label for="token-expiration-seconds">Token expires</label>
+        <label for="token-expiration-seconds">Token expires in</label>
         {% block expiration_options %}
         <select id="token-expiration-seconds"
                 class="form-control">
@@ -33,7 +33,7 @@
         </select>
         {% endblock expiration_options %}
         <small id="note-expires-at" class="form-text text-muted">
-          You can configure when your token will be expired.
+          You can configure when your token will expire.
         </small>
       </div>
     </form>
@@ -62,8 +62,8 @@
   <div class="row">
     <h2>API Tokens</h2>
     <p>
-      These are tokens with full access to the JupyterHub API.
+      These are tokens with access to the JupyterHub API.
-      Anything you can do with JupyterHub can be done with these tokens.
+      Permissions for each token may be viewed via the JupyterHub tokens API.
       Revoking the API token for a running server will require restarting that server.
     </p>
     <table class="table table-striped">
@@ -72,7 +72,7 @@
           <th>Note</th>
           <th>Last used</th>
           <th>Created</th>
-          <th>Expires at</th>
+          <th>Expires</th>
         </tr>
       </thead>
       <tbody>