Build a Jellyfin app on Finderwave.

Overview

Finderwave sits between your Jellyfin client and one or more Jellyfin servers. Users sign in once with Finderwave, see every server they own or were invited to, and open a server to get a playback URL. Your app never stores Jellyfin passwords when auth runs through Finderwave.

• Direct mode:viewers hit the owner's public Jellyfin URL. Finderwave issues a one-time ticket; the Jellyfin plugin validates it and signs the user into Jellyfin locally.
• Relay mode: viewers hit a Finderwave stream URL with a short-lived relay JWT. No port forwarding on the server side.
• Optional auth: if the server owner uses Jellyfin-native logins only, your app can connect directly to Jellyfin and skip Finderwave auth entirely.

Authentication

Register or sign in against the public auth endpoints. Responses include access_token and refresh_token (15-minute access, 30-day refresh). Send Authorization: Bearer <access_token> on protected routes.

curl -X POST https://api.finderwave.app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"your-password"}'

MFA: if the account has TOTP enabled, the login response returns {"mfa_required":true,"mfa_token":"..."}. Complete sign-in with POST /v1/auth/mfa/login using the MFA token and TOTP code.

Refresh: POST /v1/auth/refresh with the refresh token (body or fw_refresh cookie). Logout: POST /v1/auth/logout.

Servers & sessions

After login, list servers the user can access and open a playback session.

List servers

curl https://api.finderwave.app/v1/me/servers \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Returns servers[] with id, name, mode (direct or relay), auth_mode, and online status.

Create session (open server)

curl -X POST https://api.finderwave.app/v1/servers/SERVER_ID/session \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Direct + Finderwave auth: response includes view_url pointing at /Finderwave/Connect?ticket=... on the Jellyfin origin. Load that URL in a WebView or hand the ticket to your native Jellyfin client after plugin validation.

Relay: response includes view_url, session_jwt, and relay_pop. Open view_url or pass the JWT to your player stack.

Plugin validation (server-side): the Jellyfin plugin calls POST /v1/plugin/session/validate with its registration token and the ticket to obtain a Jellyfin access token for the mapped user.

Optional: GET /v1/edge/pops lists relay POPs for region selection. GET /v1/servers/:id/status returns heartbeat and version info.

Quick Connect

For TV and set-top apps without a keyboard, show a six-digit code. The user opens finderwave.app/claim (or the portal /claim) on a phone, signs in, and enters the code. Your app polls until the code is claimed, then stores the returned tokens.

1 · App requests a code

curl -X POST https://api.finderwave.app/v1/quick-connect \
  -H "Content-Type: application/json" \
  -d '{"device_name":"Living Room TV","device_type":"tv"}'

# → {"code":"482913","expires_at":"...","poll_url":"/v1/quick-connect/482913"}

Codes expire after 15 minutes. Display the code prominently on the TV.

2 · User claims on the web

Authenticated user (session cookie or bearer token): POST /v1/quick-connect/claim with {"code":"482913"}.

3 · App polls for tokens

curl https://api.finderwave.app/v1/quick-connect/482913

# pending → {"status":"pending",...}
# claimed → {"status":"claimed","access_token":"...","refresh_token":"..."}

Poll every 2–3 seconds. Stop when status is claimed or the code expires.

Jellyfin plugin

The open-source Finderwave Jellyfin plugin is recommended when you use Finderwave for authentication — it validates tickets and maps Finderwave users to Jellyfin accounts. It is not required when:

• Users connect in direct mode with Jellyfin-native auth (auth_mode: jellyfin_native).
• Your app only uses Finderwave for invites and relay, and users sign in with local Jellyfin credentials.

Server owners install the plugin from the Finderwave catalog during setup. See Getting started for install steps — the portal setup wizard marks the plugin as recommended, not mandatory, when Jellyfin-native auth is selected.

API reference (summary)

Full OpenAPI coming later. Questions: [email protected].