242 lines
7.1 KiB
Plaintext
242 lines
7.1 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
|
# Copyright (C) 2022, The Funkwhale Collective
|
|
# This file is distributed under the same license as the funkwhale package.
|
|
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
|
#
|
|
#, fuzzy
|
|
msgid ""
|
|
msgstr ""
|
|
"Project-Id-Version: funkwhale 1.2.7\n"
|
|
"Report-Msgid-Bugs-To: \n"
|
|
"POT-Creation-Date: 2022-07-23 12:18+0200\n"
|
|
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
|
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
|
"Language-Team: LANGUAGE <LL@li.org>\n"
|
|
"MIME-Version: 1.0\n"
|
|
"Content-Type: text/plain; charset=UTF-8\n"
|
|
"Content-Transfer-Encoding: 8bit\n"
|
|
|
|
#: ../../developers/authentication.rst:2
|
|
msgid "API Authentication"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:4
|
|
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:"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:67
|
|
msgid "Oauth scopes"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:70
|
|
msgid "Scope"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:71
|
|
msgid "Description"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:72
|
|
msgid "``read``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:73
|
|
msgid "Read-only access to all data (equivalent to all ``read:*`` scopes)."
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:74
|
|
msgid "``write``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:75
|
|
msgid "Read-only access to all data (equivalent to all ``write:*`` scopes)."
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:76
|
|
msgid "``<read/write>:profile``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:77
|
|
msgid "Access to profile data (e-mail address, username, etc.)"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:78
|
|
msgid "``<read/write>:libraries``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:79
|
|
msgid "Access to library data (uploads, libraries, tracks, albums, artists…)"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:80
|
|
msgid "``<read/write>:favorites``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:81
|
|
msgid "Access to favorites"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:82
|
|
msgid "``<read/write>:listenings``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:83
|
|
msgid "Access to history"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:84
|
|
msgid "``<read/write>:follows``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:85
|
|
msgid "Access to followers"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:86
|
|
msgid "``<read/write>:playlists``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:87
|
|
msgid "Access to playlists"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:88
|
|
msgid "``<read/write>:radios``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:89
|
|
msgid "Access to radios"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:90
|
|
msgid "``<read/write>:filters``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:91
|
|
msgid "Access to content filters"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:92
|
|
msgid "``<read/write>:notifications``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:93
|
|
msgid "Access to notifications"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:94
|
|
msgid "``<read/write>:edits``"
|
|
msgstr ""
|
|
|
|
#: ../../developers/authentication.rst:95
|
|
msgid "Access to metadata edits"
|
|
msgstr ""
|