msgid "Each Funkwhale API endpoint supports access from:"
msgstr ""
#: ../../developers/authentication.rst:6
msgid "Anonymous users (if the endpoint is configured to do so, for exemple via the ``API Authentication Required`` setting)"
msgstr ""
#: ../../developers/authentication.rst:7
msgid "Logged-in users"
msgstr ""
#: ../../developers/authentication.rst:8
msgid "Third-party apps (via OAuth2)"
msgstr ""
#: ../../developers/authentication.rst:10
msgid "To seamlessly support this range of access modes, we internally use oauth scopes to describes what permissions are required to perform any given operation."
msgstr ""
#: ../../developers/authentication.rst:14
msgid "OAuth"
msgstr ""
#: ../../developers/authentication.rst:17
msgid "Create an app"
msgstr ""
#: ../../developers/authentication.rst:19
msgid "To connect to Funkwhale API via OAuth, you need to create an application. There are two ways to do that:"
msgstr ""
#: ../../developers/authentication.rst:22
msgid "By visiting ``/settings/applications/new`` when logged in on your Funkwhale instance."
msgstr ""
#: ../../developers/authentication.rst:23
msgid "By sending a ``POST`` request to ``/api/v1/oauth/apps/``, as described in `our API documentation <https://docs.funkwhale.audio/swagger/>`_."
msgstr ""
#: ../../developers/authentication.rst:25
msgid "Both method will give you a client ID and secret."
msgstr ""
#: ../../developers/authentication.rst:28
msgid "Getting an access token"
msgstr ""
#: ../../developers/authentication.rst:30
msgid "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>`_."
msgstr ""
#: ../../developers/authentication.rst:33
msgid "We support the ``urn:ietf:wg:oauth:2.0:oob`` redirect URI for non-web applications, as well as traditionnal redirection-based flow."
msgstr ""
#: ../../developers/authentication.rst:36
msgid "Our authorization endpoint is located at ``/authorize``, and our token endpoint at ``/api/v1/oauth/token/``."
msgstr ""
#: ../../developers/authentication.rst:39
msgid "Refreshing tokens"
msgstr ""
#: ../../developers/authentication.rst:41
msgid "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>`_."
msgstr ""
#: ../../developers/authentication.rst:44
msgid "Security considerations"
msgstr ""
#: ../../developers/authentication.rst:46
msgid "Grant codes are valid for a 5 minutes after authorization request is approved by the end user."
msgstr ""
#: ../../developers/authentication.rst:47
msgid "Access codes are valid for 10 hours. When expired, you will need to request a new one using your refresh token."
msgstr ""
#: ../../developers/authentication.rst:48
msgid "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."
msgstr ""
#: ../../developers/authentication.rst:52
msgid "Scopes"
msgstr ""
#: ../../developers/authentication.rst:54
msgid "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:"
msgstr ""
#: ../../developers/authentication.rst:56
msgid "`read:<base_scope>`: get read-only access to the resource"
msgstr ""
#: ../../developers/authentication.rst:57
msgid "`write:<base_scope>`: get write-only access to the ressource"
msgstr ""
#: ../../developers/authentication.rst:59
msgid "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``."
msgstr ""
#: ../../developers/authentication.rst:63
msgid "Having the generic ``read`` or ``write`` scope give you the corresponding access on *all* resources."
msgstr ""
#: ../../developers/authentication.rst:65
msgid "This is the list of OAuth scopes that third-party applications can request:"