Skip to main content

​
Authentication System

Jellyfin Server provides two primary authentication methods:
  1. User Authentication - Username/password authentication that creates a session with an access token
  2. API Key Authentication - Persistent tokens for programmatic access without user credentials

​
How Authentication Works

Jellyfin uses a token-based authentication system. After successful authentication, you receive an access token that must be included in subsequent API requests.

​
Authentication Flow

  1. Authenticate using username/password or API key
  2. Receive an access token in the response
  3. Include the token in the Authorization header or query parameter for subsequent requests
  4. Token remains valid until explicitly logged out or revoked

​
User Authentication

​
Authenticate by Username

Authenticate a user with their username and password to create a new session. 
curl -X POST "http://localhost:8096/Users/AuthenticateByName" \
  -H "Content-Type: application/json" \
  -H "Authorization: MediaBrowser Client=\"MyApp\", Device=\"MyDevice\", DeviceId=\"unique-device-id\", Version=\"1.0.0\"" \
  -d '{
    "Username": "admin",
    "Pw": "password123"
  }'
​
/Users/AuthenticateByName
POST
Authenticates a user by username and password
​
Username
string
required
The username of the user account
​
Pw
string
required
The plain text password for the user
​
Authorization
string
required
Client information in MediaBrowser format: MediaBrowser Client="AppName", Device="DeviceName", DeviceId="unique-id", Version="1.0.0"
​
User
object
User information object
​
SessionInfo
object
Session information
​
AccessToken
string
Access token for authenticated requests
​
ServerId
string
Server ID

​
Response Example

{
  "User": {
    "Name": "admin",
    "Id": "6eec632a-ff0d-4d09-aad0-bf9e90b14bc6",
    "HasPassword": true,
    "HasConfiguredPassword": true,
    "HasConfiguredEasyPassword": false
  },
  "SessionInfo": {
    "Id": "a1b2c3d4e5f6",
    "UserId": "6eec632a-ff0d-4d09-aad0-bf9e90b14bc6",
    "UserName": "admin",
    "Client": "MyApp",
    "DeviceId": "unique-device-id",
    "DeviceName": "MyDevice",
    "ApplicationVersion": "1.0.0"
  },
  "AccessToken": "e8a7b6c5d4f3a2b1c0d9e8f7a6b5c4d3",
  "ServerId": "abc123def456"
}

​
Using Access Tokens

Once authenticated, include the access token in all subsequent requests using one of these methods: 
curl "http://localhost:8096/Users/Me" \
  -H "Authorization: MediaBrowser Client=\"MyApp\", Device=\"MyDevice\", DeviceId=\"unique-device-id\", Version=\"1.0.0\", Token=\"YOUR_ACCESS_TOKEN\""

​
Method 2: Query Parameter

curl "http://localhost:8096/Users/Me?ApiKey=YOUR_ACCESS_TOKEN"

​
Method 3: Legacy Headers (if enabled)

# X-Emby-Token header (legacy)
curl "http://localhost:8096/Users/Me" \
  -H "X-Emby-Token: YOUR_ACCESS_TOKEN"

# X-MediaBrowser-Token header (legacy)
curl "http://localhost:8096/Users/Me" \
  -H "X-MediaBrowser-Token: YOUR_ACCESS_TOKEN"
Legacy authorization methods (X-Emby-Token, X-MediaBrowser-Token, api_key parameter) may be disabled in server configuration. Use the standard Authorization header for best compatibility.

​
Token Management

​
Logout

End the current session and invalidate the access token.
cURL
curl -X POST "http://localhost:8096/Sessions/Logout" \
  -H "Authorization: MediaBrowser Token=\"YOUR_ACCESS_TOKEN\""
​
/Sessions/Logout
POST
Ends the current session
​
Authorization
string
required
Must include the Token to be invalidated
Response: 204 No Content

​
Get Current User

Retrieve information about the authenticated user.
cURL
curl "http://localhost:8096/Users/Me" \
  -H "Authorization: MediaBrowser Token=\"YOUR_ACCESS_TOKEN\""

​
API Key Authentication

API keys provide persistent authentication without requiring user credentials. They are ideal for:
  • Server-to-server communication
  • Long-running background services
  • Administrative automation
  • Third-party integrations
API keys have administrator-level privileges. Store them securely and never expose them in client-side code or version control.

​
Using API Keys

API keys can be used the same way as user access tokens: 
# In Authorization header
curl "http://localhost:8096/System/Info" \
  -H "Authorization: MediaBrowser Token=\"YOUR_API_KEY\""

# As query parameter
curl "http://localhost:8096/System/Info?ApiKey=YOUR_API_KEY"

​
API Key vs User Token

FeatureUser TokenAPI Key
DurationSession-based (until logout)Persistent (until manually revoked)
PermissionsUser’s permissionsAdministrator privileges
Use CaseUser-facing applicationsServer automation, integrations
CreationLogin endpointAdmin panel or API
Device InfoRequired on authenticationNot required
For detailed information on managing API keys, see the API Keys documentation.

​
Authentication Policies

Jellyfin implements several authorization policies that control access to different endpoints:
  • RequiresElevation - Requires administrator privileges
  • IgnoreParentalControl - Bypasses parental control restrictions
  • LocalAccessOrRequiresElevation - Allows local network access or requires admin
  • FirstTimeSetup - Only accessible during initial setup
  • AnonymousLanAccess - Allows anonymous access from local network

​
Error Responses

​
401 Unauthorized

Returned when authentication fails or token is invalid. 
{
  "error": "Invalid token."
}

​
403 Forbidden

Returned when the user lacks required permissions. 
{
  "error": "User account has been disabled."
}

​
404 Not Found

Returned when the user doesn’t exist. 
{
  "error": "User not found"
}

​
Security Best Practices

  1. Use HTTPS - Always use HTTPS in production to protect tokens in transit
  2. Secure Storage - Store tokens securely (encrypted storage, secure cookies, environment variables)
  3. Token Rotation - Implement token refresh mechanisms for long-lived applications
  4. Least Privilege - Use user tokens with appropriate permissions instead of API keys when possible
  5. Revoke Unused Tokens - Regularly audit and revoke unused API keys and sessions
  6. Client Information - Always provide accurate client information in the Authorization header

​
Next Steps

API Keys

Create and manage persistent API keys

User Management

Manage user accounts and permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us