Something wrong with the translation?

Help us to improve it on our translation platform

API authentication

Funkwhale uses the OAuth authorization grant flow for external apps. This flow is a secure way to authenticate apps that requires a user’s explicit consent to perform actions.

%%{init: { 'sequence': {'mirrorActors': false} } }%% sequenceDiagram accTitle: "Funkwhale OAuth token flow" accDescr: "A sequence diagram showing how apps authenticate with Funkwhale" autonumber actor User participant A as Application participant F as Funkwhale web interface participant T as Token endpoint User ->> A: Log in to Funkwhale A ->> F: Direct to login screen F -->> User: Authenticate this app? User ->> F: Confirm F -->> A: Authorization code A ->> T: Authorization code and redirect URI T -->> A: Access token and refresh token loop Refresh A ->> T: Refresh token T -->> A: Access token end

1. Create an application

To connect to the Funkwhale API using OAuth, you need to create an application. This represents the entity credentials are related to.

When creating an application you need to define the scopes the application has access to. Scopes define what information your application can access. Each scope can be granted with the following rights:

  • read:<scope>: grants read-only access to the resource

  • write:<scope>: grants write-only access to the resource

read rights are required to fetch information using a GET request. All other actions (POST, PATCH, PUT, and DELETE) require write privileges. You may give an application both read and write access to any scope.

Scope

Description

read

Read-only access to all data

write

Read-only access to all data

<read/write>:profile

Access to profile data (email address, username, etc.)

<read/write>:libraries

Access to library data (uploads, libraries, tracks, albums, artists, etc.)

<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

Next, you need to define a Redirect URI. This is the location the user is redirected to once they authenticate your app. This can be any URI you want.

Note

Funkwhale supports the urn:ietf:wg:oauth:2.0:oob redirect URI for non-web applications. If you use this URI, the user is shown a token to copy and paste.

Once you’ve decided on your scopes and your redirect URI, you can create your app using one of the following methods:

  1. Visit /settings/applications/new on your Funkwhale pod while logged in

  2. Send a POST request to /api/v1/oauth/apps. See our API documentation for more information

Both methods return a client ID and a secret.

2. Get an authorization code

Important

Authorization codes are only valid for 5 minutes after the user approves the request.

You need an authorization code to request an access token for your user. This code confirms to the server that a user has authorized access to their account.

To fetch an authorization code, you need to send the user to their Funkwhale pod to authenticate. This sends an authorization request to the server.

To do this, call the /authorize endpoint with the following URL encoded query parameters:

  • client_id* - Your application’s client ID

  • response_type* - Must be set to code.

  • redirect_uri - Your redirect URI

  • scope - A list of scopes

  • state - Used to maintain state between the request and the callback to prevent cross-site request forgery. Typically corresponds with a location in the app (e.g. /library)

Here is an example URL: https://demo.funkwhale.audio/authorize?response_type=code&scope=read%20write&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fauth%2Fcallback&state=/library&client_id=jDOUfhqLlrbuOkToDCanZmBKEiyorMb9ZUgD2tFQ.

When the user authorizes your app, the server responds with an authorization code. See the OAuth spec for more information about this response.

3. Get an access token

Once you receive your authorization code, you need to request an access token. To request an access token, call the /api/v1/oauth/token endpoint with the following information:

  • grant_type* - Must be set to authorization_code

  • code* - Your application’s authorization code

  • redirect_uri* - Your redirect URI

  • client_id* Your application’s client ID

The server responds with an access_token and a refresh_token. See the OAuth spec for more information about this response.

You can use this token to authenticate calls from your application to the Funkwhale API by passing it as a request header with the following format: Authorization: Bearer <token>.

4. Refresh your access token

Important

When you refresh your token the endpoint returns a new refresh_token. You must update your refresh token each time you request a new access token.

By default, Funkwhale access tokens are valid for 10 hours. Pod admins can configure this by setting the ACCESS_TOKEN_EXPIRE_SECONDS variable in their .env file.

After the access token expires, you must request a new access token by calling the /api/v1/oauth/token endpoint with the following information:

  • grant_type* - Must be set to refresh_token

  • refresh_token* - Your current refresh token

  • scope - A list of scopes

See the OAuth spec for more information about this response.