plexjs/docs/sdks/authentication

Authentication

(authentication)

Overview

API Calls regarding authentication for Plex Media Server

Available Operations

• getTransientToken - Get a Transient Token.
• getSourceConnectionInformation - Get Source Connection Information
• getUserDetails - Get User Data By Token
• postUsersSignInData - Get User SignIn Data

getTransientToken

This endpoint provides the caller with a temporary token with the same access level as the caller's token. These tokens are valid for up to 48 hours and are destroyed if the server instance is restarted.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";
import { GetTransientTokenQueryParamType, Scope } from "@lukehagar/plexjs/sdk/models/operations";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const result = await plexAPI.authentication.getTransientToken(GetTransientTokenQueryParamType.Delegation, Scope.All);
  
  // Handle the result
  console.log(result)
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { authenticationGetTransientToken } from "@lukehagar/plexjs/funcs/authenticationGetTransientToken.js";
import { GetTransientTokenQueryParamType, Scope } from "@lukehagar/plexjs/sdk/models/operations";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const res = await authenticationGetTransientToken(plexAPI, GetTransientTokenQueryParamType.Delegation, Scope.All);

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description
type	operations.GetTransientTokenQueryParamType	✔️	delegation - This is the only supported type parameter.
scope	operations.Scope	✔️	all - This is the only supported scope parameter.
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.GetTransientTokenResponse>

Errors

Error Object	Status Code	Content Type
errors.GetTransientTokenResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

getSourceConnectionInformation

If a caller requires connection details and a transient token for a source that is known to the server, for example a cloud media provider or shared PMS, then this endpoint can be called. This endpoint is only accessible with either an admin token or a valid transient token generated from an admin token. Note: requires Plex Media Server >= 1.15.4.

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const result = await plexAPI.authentication.getSourceConnectionInformation("server://client-identifier");
  
  // Handle the result
  console.log(result)
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { authenticationGetSourceConnectionInformation } from "@lukehagar/plexjs/funcs/authenticationGetSourceConnectionInformation.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const res = await authenticationGetSourceConnectionInformation(plexAPI, "server://client-identifier");

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description	Example
source	string	✔️	The source identifier with an included prefix.	[object Object]
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.GetSourceConnectionInformationResponse>

Errors

Error Object	Status Code	Content Type
errors.GetSourceConnectionInformationResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

getUserDetails

Get the User data from the provided X-Plex-Token

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  accessToken: "<YOUR_API_KEY_HERE>",
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const result = await plexAPI.authentication.getUserDetails("CV5xoxjTpFKUzBTShsaf");
  
  // Handle the result
  console.log(result)
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { authenticationGetUserDetails } from "@lukehagar/plexjs/funcs/authenticationGetUserDetails.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  accessToken: "<YOUR_API_KEY_HERE>",
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const res = await authenticationGetUserDetails(plexAPI, "CV5xoxjTpFKUzBTShsaf");

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description	Example
xPlexToken	string	✔️	Plex Authentication Token	[object Object]
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.
options.serverURL	string	➖	An optional server URL to use.	http://localhost:8080

Response

Promise<operations.GetUserDetailsResponse>

Errors

Error Object	Status Code	Content Type
errors.GetUserDetailsResponseBody	401	application/json
errors.SDKError	4xx-5xx	/

postUsersSignInData

Sign in user with username and password and return user data with Plex authentication token

Example Usage

import { PlexAPI } from "@lukehagar/plexjs";

const plexAPI = new PlexAPI({
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const result = await plexAPI.authentication.postUsersSignInData("gcgzw5rz2xovp84b4vha3a40", {
    login: "username@email.com",
    password: "password123",
  });
  
  // Handle the result
  console.log(result)
}

run();

Standalone function

The standalone function version of this method:

import { PlexAPICore } from "@lukehagar/plexjs/core.js";
import { authenticationPostUsersSignInData } from "@lukehagar/plexjs/funcs/authenticationPostUsersSignInData.js";

// Use `PlexAPICore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const plexAPI = new PlexAPICore({
  xPlexClientIdentifier: "gcgzw5rz2xovp84b4vha3a40",
});

async function run() {
  const res = await authenticationPostUsersSignInData(plexAPI, "gcgzw5rz2xovp84b4vha3a40", {
    login: "username@email.com",
    password: "password123",
  });

  if (!res.ok) {
    throw res.error;
  }

  const { value: result } = res;

  // Handle the result
  console.log(result)
}

run();

Parameters

Parameter	Type	Required	Description	Example
xPlexClientIdentifier	string	➖	The unique identifier for the client application This is used to track the client application and its usage (UUID, serial number, or other number unique per device)	[object Object]
requestBody	operations.PostUsersSignInDataRequestBody	➖	Login credentials
options	RequestOptions	➖	Used to set various options for making HTTP requests.
options.fetchOptions	RequestInit	➖	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All Request options, except method and body, are allowed.
options.retries	RetryConfig	➖	Enables retrying HTTP requests under certain failure conditions.
options.serverURL	string	➖	An optional server URL to use.	http://localhost:8080

Response

Promise<operations.PostUsersSignInDataResponse>

Errors

Error Object	Status Code	Content Type
errors.PostUsersSignInDataResponseBody	401	application/json
errors.SDKError	4xx-5xx	/