plexjava/docs/sdks/authentication/README.md

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

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.GetTransientTokenQueryParamType;
import dev.plexapi.sdk.models.operations.GetTransientTokenResponse;
import dev.plexapi.sdk.models.operations.Scope;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            GetTransientTokenResponse res = sdk.authentication().getTransientToken()
                .type(GetTransientTokenQueryParamType.DELEGATION)
                .scope(Scope.ALL)
                .call();

            // handle response
        } catch (dev.plexapi.sdk.models.errors.GetTransientTokenResponseBody e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter	Type	Required	Description
type	GetTransientTokenQueryParamType	✔️	delegation - This is the only supported type parameter.
scope	Scope	✔️	all - This is the only supported scope parameter.

Response

GetTransientTokenResponse

Errors

Error Object	Status Code	Content Type
models/errors/GetTransientTokenResponseBody	401	application/json
models/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

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.GetSourceConnectionInformationResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            GetSourceConnectionInformationResponse res = sdk.authentication().getSourceConnectionInformation()
                .source("server://client-identifier")
                .call();

            // handle response
        } catch (dev.plexapi.sdk.models.errors.GetSourceConnectionInformationResponseBody e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter	Type	Required	Description	Example
source	String	✔️	The source identifier with an included prefix.	server://client-identifier

Response

GetSourceConnectionInformationResponse

Errors

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

getUserDetails

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

Example Usage

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.GetUserDetailsResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .accessToken("<YOUR_API_KEY_HERE>")
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            GetUserDetailsResponse res = sdk.authentication().getUserDetails()
                .xPlexToken("CV5xoxjTpFKUzBTShsaf")
                .call();

            if (res.userPlexAccount().isPresent()) {
                // handle response
            }
        } catch (dev.plexapi.sdk.models.errors.GetUserDetailsResponseBody e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter	Type	Required	Description	Example
xPlexToken	String	✔️	Plex Authentication Token	CV5xoxjTpFKUzBTShsaf
serverURL	String	➖	An optional server URL to use.	http://localhost:8080

Response

GetUserDetailsResponse

Errors

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

postUsersSignInData

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

Example Usage

package hello.world;

import dev.plexapi.sdk.PlexAPI;
import dev.plexapi.sdk.models.errors.SDKError;
import dev.plexapi.sdk.models.operations.PostUsersSignInDataRequestBody;
import dev.plexapi.sdk.models.operations.PostUsersSignInDataResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {
        try {
            PlexAPI sdk = PlexAPI.builder()
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .build();

            PostUsersSignInDataResponse res = sdk.authentication().postUsersSignInData()
                .xPlexClientIdentifier("gcgzw5rz2xovp84b4vha3a40")
                .requestBody(PostUsersSignInDataRequestBody.builder()
                    .login("username@email.com")
                    .password("password123")
                    .build())
                .call();

            if (res.userPlexAccount().isPresent()) {
                // handle response
            }
        } catch (dev.plexapi.sdk.models.errors.PostUsersSignInDataResponseBody e) {
            // handle exception
            throw e;
        } catch (SDKError e) {
            // handle exception
            throw e;
        } catch (Exception e) {
            // handle exception
            throw e;
        }

    }
}

Parameters

Parameter	Type	Required	Description	Example
xPlexClientIdentifier	Optional	➖	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)	gcgzw5rz2xovp84b4vha3a40
requestBody	Optional	➖	Login credentials
serverURL	String	➖	An optional server URL to use.	http://localhost:8080

Response

PostUsersSignInDataResponse

Errors

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