pgsql-jellyfin/docs/WEBSOCKET_AUTHENTICATION.md

WebSocket Authentication Guide

Overview

WebSocket connections to Jellyfin servers require authentication. This guide explains how to properly authenticate WebSocket connections using API tokens.

Authentication Methods

1. Query String Parameter (Recommended for WebSocket)

The simplest and most compatible method for WebSocket connections.

URL Format:

ws://jellyfin-server:8096/socket?api_key=YOUR_API_TOKEN
wss://jellyfin-server:8096/socket?api_key=YOUR_API_TOKEN  (for HTTPS)

JavaScript Example:

const token = "YOUR_API_KEY";
const ws = new WebSocket(`ws://jellyfin-server:8096/socket?api_key=${token}`);

ws.onopen = function(event) {
	console.log("WebSocket connection established with authentication");
};

ws.onerror = function(event) {
	console.error("WebSocket error:", event);
};

ws.onmessage = function(event) {
	const message = JSON.parse(event.data);
	console.log("Received message:", message);
};

ws.onclose = function(event) {
	console.log("WebSocket connection closed");
};

Python Example:

import asyncio
import websockets
import json

async def connect_with_token():
	token = "YOUR_API_KEY"
	uri = f"ws://jellyfin-server:8096/socket?api_key={token}"

	async with websockets.connect(uri) as websocket:
		print("Connected to Jellyfin WebSocket")

		# Receive messages
		async for message in websocket:
			data = json.loads(message)
			print(f"Received: {data}")

asyncio.run(connect_with_token())

C# Example:

using System;
using System.Net.WebSockets;
using System.Threading;
using System.Threading.Tasks;

public class JellyfinWebSocketClient
{
	public async Task ConnectAsync(string serverUrl, string token)
	{
		var uri = new Uri($"ws://{serverUrl}:8096/socket?api_key={token}");

		using (var client = new ClientWebSocket())
		{
			await client.ConnectAsync(uri, CancellationToken.None);

			Console.WriteLine("Connected to Jellyfin WebSocket");

			// Receive messages
			var buffer = new byte[1024 * 4];
			while (client.State == WebSocketState.Open)
			{
				var result = await client.ReceiveAsync(
					new ArraySegment<byte>(buffer),
					CancellationToken.None);

				if (result.MessageType == WebSocketMessageType.Text)
				{
					var message = System.Text.Encoding.UTF8.GetString(
						buffer, 0, result.Count);
					Console.WriteLine($"Received: {message}");
				}
			}
		}
	}
}

2. Authorization Header (Alternative)

For advanced use cases, you can also use the Authorization header.

Header Format:

Authorization: MediaBrowser Device="ClientName", DeviceId="unique-id", Version="1.0", Token="YOUR_API_TOKEN"

Note: Some WebSocket implementations may not support custom headers during the upgrade handshake. Query parameters are recommended.

Obtaining an API Token

Via Server UI

1. Navigate to your Jellyfin server dashboard
2. Go to Settings → API Keys (or similar, depending on version)
3. Create a new API key
4. Copy the token to use in your WebSocket connection

Programmatically

Use the REST API to create API keys:

curl -X POST "http://jellyfin-server:8096/Auth/Keys" \
  -H "Authorization: MediaBrowser Token=existing_token" \
  -H "Content-Type: application/json" \
  -d '{"AppName": "My WebSocket Client"}'

Common Issues

Connection Refused / 401 Unauthorized

• Verify the API token is correct
• Ensure the token hasn't expired
• Check that the WebSocket endpoint path is correct (/socket)

Token Not Found

• Verify the query parameter is URL-encoded properly
• Ensure the parameter name is correct: api_key (lowercase)
• Check server logs for authentication errors

WebSocket Connection Fails Immediately

• Confirm the server is reachable
• Check firewall rules allow WebSocket connections
• Try with wss:// (secure WebSocket) if using HTTPS

Server Configuration

The server automatically extracts tokens from:

1. Authorization header (MediaBrowser Token parameter)
2. Query string api_key parameter
3. Query string ApiKey parameter
4. Legacy headers (if enabled in config)

No special server configuration is required for WebSocket authentication to work.

Security Considerations

• Always use wss:// (secure WebSocket) when connecting over untrusted networks
• Keep API tokens secure and rotate them periodically
• Use separate tokens for different clients/applications
• Consider implementing token expiration in your server configuration

See Also

• Jellyfin API Documentation
• WebSocket Protocol (RFC 6455)