Changeset View
Changeset View
Standalone View
Standalone View
docs/index.rst
.. _swh-web-client: | .. _swh-web-client: | ||||
.. include:: README.rst | .. include:: README.rst | ||||
.. _swh-web-client-auth: | |||||
Authentication | Authentication | ||||
-------------- | -------------- | ||||
If you have a user account registered on `Software Heritage Identity Provider`_, | 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 | it is possible to authenticate requests made to the Web APIs through the use of | ||||
OpenID Connect bearer tokens. Sending authenticated requests can notably | OpenID Connect bearer tokens. Sending authenticated requests can notably | ||||
allow to lift API rate limiting depending on your permissions. | allow to lift API rate limiting depending on your permissions. | ||||
▲ Show 20 Lines • Show All 63 Lines • ▼ Show 20 Lines | |||||
it anytime while it is valid to get an access token without having to login | it anytime while it is valid to get an access token without having to login | ||||
again. | again. | ||||
.. code-block:: text | .. code-block:: text | ||||
$ swh auth refresh $REFRESH_TOKEN | $ 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:: | |||||
from swh.web.client import WebAPIClient | |||||
REFRESH_TOKEN = '.......' # Use "swh auth login" command to get it | |||||
client = WebAPIClient() | |||||
client.authenticate(REFRESH_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 | It is also possible to ``logout`` from the authenticated OpenID Connect session | ||||
which invalidates all previously emitted tokens. | which invalidates all previously emitted tokens. | ||||
.. code-block:: text | .. code-block:: text | ||||
$ swh auth logout $REFRESH_TOKEN | $ swh auth logout $REFRESH_TOKEN | ||||
Successfully logged out from OpenID Connect session | Successfully logged out from OpenID Connect session | ||||
API Reference | API Reference | ||||
------------- | ------------- | ||||
.. toctree:: | .. toctree:: | ||||
:maxdepth: 2 | :maxdepth: 2 | ||||
/apidoc/swh.web.client | /apidoc/swh.web.client | ||||
.. _Software Heritage Identity Provider: | .. _Software Heritage Identity Provider: | ||||
https://auth.softwareheritage.org/auth/realms/SoftwareHeritage/account/ | https://auth.softwareheritage.org/auth/realms/SoftwareHeritage/account/ | ||||
No newline at end of file | No newline at end of file |