funkwhale/api

Funkwhale API

This is the Funkwhale API. Check out our API explorer for interactive documentation.

OAuth 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. You can use our demo server at https://demo.funkwhale.audio for testing purposes.

To authenticate with the Funkwhale API:

1. Create an application by sending a POST request to api/v1/oauth/apps. Include your scopes and redirect URI (use urn:ietf:wg:oauth:2.0:oob to get an authorization code you can copy)
2. Send an authorization request to the /authorize endpoint to receive an authorization code
3. Request an access token from /api/v1/oauth/token
4. Use your access token to authenticate your calls with the following format: Authorization: Bearer <token>
5. Refresh your access token by sending a refresh request to /api/v1/oauth/token

For more detailed instructions, see our API authentication documentation.

Application token authentication

If you have an account on your target pod, you can create an application at /settings/applications/new. Once you authorize the application you can retrieve an access token. Use your access token to authenticate your calls with the following format: Authorization: Bearer <token>

Rate limiting

Funkwhale supports rate-limiting as of version 0.2.0. Pod admins can choose to rate limit specific endpoints to prevent abuse and improve the stability of the service. If the server drops a request due to rate-limiting, it returns a 429 status code.

Each API call returns HTTP headers to pass the following information:

• What was the scope of the request (X-RateLimit-Scope)
• What is the rate-limit associated with the request scope (X-RateLimit-Limit)
• How many more requests in the scope can be made within the rate-limit timeframe (X-RateLimit-Remaining)
• How much time does the client need to wait to send another request (Retry-After)

For more information, check our rate limit documentation

Resources

For more information about API usage, refer to our API documentation.