Verified Commit d375c210 authored by Eliot Berriot's avatar Eliot Berriot
Browse files

See #752: Documentation

parent aadebbaa
Pipeline #3698 passed with stages
in 3 minutes and 4 seconds
......@@ -361,6 +361,8 @@ OAUTH2_PROVIDER = {
"ALLOWED_REDIRECT_URI_SCHEMES": ["http", "https", "urn"],
# we keep expired tokens for 15 days, for tracability
......@@ -33,4 +33,4 @@ special permissions, such as modifying instance settings or moderation (but this
enabled in a future release).
If you want to start building an app on top of Funkwhale's API, please check-out
``_ and ``_.
......@@ -5,13 +5,51 @@ 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 OAuth)
- 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.
Our OAuth scopes
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 <>`_.
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 <>`_.
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 <>`_.
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 are defined in :file:`funkwhale_api/users/oauth/`, and generally are mapped to a business-logic resources (follows, favorites, etc.). All those base scopes come in two flawours:
......@@ -24,22 +62,36 @@ to perform read operations on playlists such as fetching a given playlist via ``
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:
How do we grant scopes on requests
Internally, we specify for each of our API endpoints what base scope is associated to the resource
served by the endpoint. Depending on the request method, we'll then require an actual scope to
be available on the request. If our endpoint is mapped to the ``playlists`` base scope:
- ``GET`` requests will need the ``read:playlists`` scope
- ``POST``, ``PATCH``, ``PUT`` or ``DELETE`` requests will need the ``write:playlists`` scope
we grant scopes to the request, as described below:
- OAuth requests (using a valid OAuth token) get the scopes from the token that is used to perform access
- Requests made by users logged in via session/cookie requests get all the base scopes and additional management scopes if relevant (e.g if they have moderation/library/settings permissions)
- Every other request is considered as anonymous. If the endpoints allows anonymous access, the request gets a subset of read-only scopes that are suited for anonymous connexions
Once we have set request scopes, we compare those scopes with the scope required by our endpoint and
return a 403 Response if the required scope is missing.
| 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 |
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment