API Reference

API RefereAPI Referencence

All endpoints are under the base path /sso/. Admin endpoints require an API key passed as:

Authorization: MediaBrowser Token="<your-api-key>"

Generate an API key in Jellyfin under Administration → API Keys.

---

OpenID Connect Endpoints

Authentication Flow

Method	Path	Description
GET	/sso/OID/start/{provider}	Initiates the OIDC flow. Redirects the browser to the identity provider.
GET	/sso/OID/redirect/{provider}	OIDC callback endpoint. The identity provider redirects here after login.
POST	/sso/OID/Auth/{provider}	Client-side authentication. Used by the web UI after the redirect.

Admin Configuration

Method	Path	Auth Required	Description
POST	/sso/OID/Add/{provider}	API key	Add or update an OIDC provider configuration.
GET	/sso/OID/Del/{provider}	API key	Delete an OIDC provider configuration.
GET	/sso/OID/Get	API key + elevated	List all OIDC provider configurations.
GET	/sso/OID/GetNames	None	List OIDC provider names (public, used by UI).
GET	/sso/OID/States	API key + elevated	List active OIDC flows (debug).

Add/Update OIDC Provider Request Body

{
  "oidEndpoint": "https://your-idp.example.com",
  "oidClientId": "jellyfin",
  "oidSecret": "your-client-secret",
  "enabled": true,
  "enableAuthorization": true,
  "enableAllFolders": false,
  "enabledFolders": [],
  "adminRoles": ["jellyfin-admins"],
  "preserveAdminPermissions": false,
  "roles": ["jellyfin-users"],
  "roleClaim": "groups",
  "oidScopes": ["groups"],
  "defaultUsernameClaim": "preferred_username",
  "avatarUrlFormat": "",
  "enableFolderRoles": false,
  "folderRoleMapping": [],
  "enableLiveTvRoles": false,
  "enableLiveTv": false,
  "enableLiveTvManagement": false,
  "liveTvRoles": [],
  "liveTvManagementRoles": [],
  "disableHttps": false,
  "disablePushedAuthorization": false,
  "doNotValidateEndpoints": false,
  "doNotValidateIssuerName": false,
  "doNotLoadProfile": false,
  "schemeOverride": "",
  "portOverride": null
}

preserveAdminPermissions defaults to false. With the default strict behavior, admin status is removed when enableAuthorization is enabled and the login does not match an admin role. Set it to true to allow SSO roles to elevate administrators without demoting accounts that are already administrators.

---

SAML Endpoints

Authentication Flow

Method	Path	Description
GET	/sso/SAML/start/{provider}	Initiates the SAML flow.
GET	/sso/SAML/p/{provider}	Alias for start.
POST	/sso/SAML/post/{provider}	SAML assertion callback (ACS endpoint).
POST	/sso/SAML/p/{provider}	Alias for post (ACS endpoint).
POST	/sso/SAML/Auth/{provider}	Client-side authentication.

Admin Configuration

Method	Path	Auth Required	Description
POST	/sso/SAML/Add/{provider}	API key	Add or update a SAML provider configuration.
GET	/sso/SAML/Del/{provider}	API key	Delete a SAML provider configuration.
GET	/sso/SAML/Get	API key + elevated	List all SAML provider configurations.
GET	/sso/SAML/GetNames	None	List SAML provider names (public).

Add/Update SAML Provider — Request Body

{
  "samlEndpoint": "https://your-idp.example.com/saml/metadata",
  "samlClientId": "jellyfin",
  "samlCertificate": "<base64-encoded-x509-certificate>",
  "enabled": true,
  "enableAuthorization": true,
  "enableAllFolders": false,
  "enabledFolders": [],
  "adminRoles": ["jellyfin-admins"],
  "preserveAdminPermissions": false,
  "roles": ["jellyfin-users"],
  "enableFolderRoles": false,
  "folderRoleMapping": [],
  "enableLiveTvRoles": false,
  "enableLiveTv": false,
  "enableLiveTvManagement": false,
  "liveTvRoles": [],
  "liveTvManagementRoles": [],
  "schemeOverride": "",
  "portOverride": null
}

preserveAdminPermissions has the same behavior as OIDC and defaults to false.

---

Account Linking Endpoints

Method	Path	Auth Required	Description
POST	/sso/{mode}/Link/{provider}/{jellyfinUserId}	User or admin	Link an SSO identity to a Jellyfin user.
DELETE	/sso/{mode}/Link/{provider}/{jellyfinUserId}/{canonicalName}	User or admin	Remove a specific SSO link.
GET	/sso/oid/links/{jellyfinUserId}	User or admin	List all OIDC links for a user.
GET	/sso/saml/links/{jellyfinUserId}	User or admin	List all SAML links for a user.

{mode} is oid or saml.

Users may only modify their own links. Admins may modify any user's links.

---

User Management

Method	Path	Auth Required	Description
POST	/sso/Unregister/{username}	API key + elevated	Remove a user from SSO and assign a new auth provider.

Unregister request body (plain string):

"Jellyfin.Server.Implementations.Users.DefaultAuthenticationProvider"

---

Error Responses

All endpoints return standard HTTP status codes:

Code	Meaning
200	Success
400	Bad request (malformed input)
401	Unauthorized (missing or invalid API key)
403	Forbidden (insufficient permissions)
404	Provider not found
500	Internal server error (check Jellyfin logs)