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:
By visiting
/settings/applications/new
when logged in on your Funkwhale instance.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
Scopes are defined in 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-only access to all data
(equivalent to all |
|
Write-only access to all data
(equivalent to all |
|
Access to profile data (e-mail address, username, etc.) |
|
Access to library data (uploads, libraries tracks, albums, artists…) |
|
Access to favorites |
|
Access to history |
|
Access to followers |
|
Access to playlists |
|
Access to radios |
|
Access to content filters |
|
Access to notifications |
|
Access to metadata edits |