kopia lustrzana https://dev.funkwhale.audio/funkwhale/funkwhale
98 wiersze
5.5 KiB
ReStructuredText
98 wiersze
5.5 KiB
ReStructuredText
API Authentication
|
|
==================
|
|
|
|
Each Funkwhale API endpoint supports access from:
|
|
|
|
- Anonymous users (if the endpoint is configured to do so, for exemple via the ``API Authentication Required`` setting)
|
|
- Logged-in users
|
|
- Third-party apps (via OAuth2)
|
|
|
|
To seamlessly support this range of access modes, we internally use oauth scopes
|
|
to describes what permissions are required to perform any given operation.
|
|
|
|
OAuth
|
|
-----
|
|
|
|
Create an app
|
|
:::::::::::::
|
|
|
|
To connect to Funkwhale API via OAuth, you need to create an application. There are
|
|
two ways to do that:
|
|
|
|
1. By visiting ``/settings/applications/new`` when logged in on your Funkwhale instance.
|
|
2. By sending a ``POST`` request to ``/api/v1/oauth/apps/``, as described in `our API documentation <https://docs.funkwhale.audio/swagger/>`_.
|
|
|
|
Both method will give you a client ID and secret.
|
|
|
|
Getting an access token
|
|
:::::::::::::::::::::::
|
|
|
|
Once you have a client ID and secret, you can request access tokens
|
|
using the `authorization code grant flow <https://tools.ietf.org/html/rfc6749#section-4.1>`_.
|
|
|
|
We support the ``urn:ietf:wg:oauth:2.0:oob`` redirect URI for non-web applications, as well
|
|
as traditionnal redirection-based flow.
|
|
|
|
Our authorization endpoint is located at ``/authorize``, and our token endpoint at ``/api/v1/oauth/token/``.
|
|
|
|
Refreshing tokens
|
|
:::::::::::::::::
|
|
|
|
When your access token is expired, you can `request a new one as described in the OAuth specification <https://tools.ietf.org/html/rfc6749#section-6>`_.
|
|
|
|
Security considerations
|
|
:::::::::::::::::::::::
|
|
|
|
- Grant codes are valid for a 5 minutes after authorization request is approved by the end user.
|
|
- Access codes are valid for 10 hours. When expired, you will need to request a new one using your refresh token.
|
|
- We return a new refresh token everytime an access token is requested, and invalidate the old one. Ensure you store the new refresh token in your app.
|
|
|
|
|
|
Scopes
|
|
::::::
|
|
|
|
Scopes are defined in :file:`funkwhale_api/users/oauth/scopes.py:BASE_SCOPES`, and generally are mapped to a business-logic resources (follows, favorites, etc.). All those base scopes come in two flawours:
|
|
|
|
- `read:<base_scope>`: get read-only access to the resource
|
|
- `write:<base_scope>`: get write-only access to the ressource
|
|
|
|
For example, ``playlists`` is a base scope, and ``write:playlists`` is the actual scope needed to perform write
|
|
operations on playlists (via a ``POST``, ``PATCH``, ``PUT`` or ``DELETE``. ``read:playlists`` is used
|
|
to perform read operations on playlists such as fetching a given playlist via ``GET``.
|
|
|
|
Having the generic ``read`` or ``write`` scope give you the corresponding access on *all* resources.
|
|
|
|
This is the list of OAuth scopes that third-party applications can request:
|
|
|
|
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| Scope | Description |
|
|
+===========================================+===================================================+
|
|
| ``read`` | Read-only access to all data |
|
|
| | (equivalent to all ``read:*`` scopes) |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``write`` | Write-only access to all data |
|
|
| | (equivalent to all ``write:*`` scopes) |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:profile`` | Access to profile data (email, username, etc.) |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:libraries`` | Access to library data (uploads, libraries |
|
|
| | tracks, albums, artists...) |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:favorites`` | Access to favorites |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:listenings`` | Access to history |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:follows`` | Access to followers |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:playlists`` | Access to playlists |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:radios`` | Access to radios |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:filters`` | Access to content filters |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:notifications`` | Access to notifications |
|
|
+-------------------------------------------+---------------------------------------------------+
|
|
| ``<read/write>:edits`` | Access to metadata edits |
|
|
+-------------------------------------------+---------------------------------------------------+
|