Antoine Lambert · f3d89ebc
--- a/docs/index.rst

+ 12

− 41
+++ b/docs/index.rst

+ 12

− 41
 @@ -9,10 +9,10 @@ Authentication

 If you have a user account registered on `Software Heritage Identity Provider`_,
 it is possible to authenticate requests made to the Web APIs through the use of
-OpenID Connect bearer tokens. Sending authenticated requests can notably
+a OpenID Connect bearer token. Sending authenticated requests can notably
 allow to lift API rate limiting depending on your permissions.

-To get these tokens, a dedicated CLI tool is made available when installing
+To get this token, a dedicated CLI tool is made available when installing
 ``swh-web-client``:

 .. code-block:: text
 @@ -37,70 +37,41 @@ To get these tokens, a dedicated CLI tool is made available when installing
  Commands:
    login    Login and create new offline OpenID Connect session.
    logout   Logout from an offline OpenID Connect session.
-    refresh  Refresh an offline OpenID Connect session.

 In order to get your tokens, you need to use the ``login`` subcommand of
 that CLI tool by passing your username as argument. You will be prompted
 for your password and if the authentication succeeds a new OpenID Connect
-session will be created and tokens will be dumped in JSON format to standard
-output.
+session will be created and tokens will be dumped to standard output.

 .. code-block:: text

  $ swh auth login <username>
  Password:
-  {
-      "access_token": ".......",
-      "expires_in": 600,
-      "refresh_expires_in": 0,
-      "refresh_token": ".......",
-      "token_type": "bearer",
-      "id_token": ".......",
-      "not-before-policy": 1584551170,
-      "session_state": "c14e1b7b-8263-4852-bd1c-adc7bc12a136",
-      "scope": "openid email profile offline_access"
-  }
-
-To authenticate yourself, you need to send the ``access_token`` value in
-request headers when querying the Web APIs.
-Considering you have stored the ``access_token`` value in a TOKEN environment
+  eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmNjMzMD...
+
+To authenticate yourself, you need to send that token value in request headers
+when querying the Web API.
+Considering you have stored that token value in a TOKEN environment
 variable, you can perform an authenticated call the following way using ``curl``:

 .. code-block:: text

  $ curl -H "Authorization: Bearer ${TOKEN}" https://archive.softwareheritage.org/api/1/<endpoint>

-The access token has a short living period (usually ten minutes) and must be
-renewed on a regular basis by passing the ``refresh_token`` value as argument
-of the ``refresh`` subcommand of the CLI tool. The new access token will be
-dumped in JSON format to standard output. Note that the refresh token has a
-much longer living period (usually several dozens of days) so you can use
-it anytime while it is valid to get an access token without having to login
-again.
-
-.. code-block:: text
-
-  $ swh auth refresh $REFRESH_TOKEN
-  "......."
-
 Note that if you intend to use the :class:`swh.web.client.client.WebAPIClient`
-class, the access token renewal will be automatically handled if you call
-method :meth:`swh.web.client.client.WebAPIClient.authenticate` prior to
-sending any requests. To activate authentication, use the following code snippet::
+class, you can activate authentication by using the following code snippet::

  from swh.web.client import WebAPIClient

-  REFRESH_TOKEN = '.......'  # Use "swh auth login" command to get it
+  TOKEN = '.......'  # Use "swh auth login" command to get it

-  client = WebAPIClient()
-  client.authenticate(REFRESH_TOKEN)
+  client = WebAPIClient(bearer_token=TOKEN)

  # All requests to the Web API will be authenticated
  resp = client.get('swh:1:rev:aafb16d69fd30ff58afdd69036a26047f3aebdc6')

 It is also possible to ``logout`` from the authenticated OpenID Connect session
-which invalidates all previously emitted tokens.
-
+which definitely revokes the token.

 .. code-block:: text