Developer Portal Account

To access the Plex APIs in the developer portal, you must have Plex IAM activated.


Logging in to the developer portal
  1. Work with your Plex Champion to file a support ticket at https://plex.my.site.com/community/s/my-plex by providing all necessary details
  2. Upon confirming the case is resolved, access https://developers.plex.com/
  3. Enter your company name in the company code section. Click Next
  4. Enter your company email ID. Click Next
  5. Enter your password. Click Next

Obtaining API credentials

To obtain your API credentials, you must first set up a developer portal account following the steps above. Only users with developer portal accounts can create API keys.

To obtain your API credentials (Consumer Key and Consumer Secret), create an application in the Plex Developer Portal.

  1. Access the Plex Developer Portal at https://developers.plex.com/.
  2. Click on your account name and select My Apps.
  3. Click Add a New App.
  4. On the Add App screen, enter a name for your app.
  5. For Product (also known as API categories), select the API products you want to access to.
  6. Click Create App.

The Consumer Key and Consumer Secret is generated for your application and appears on the screen.


Request Headers

Subscription Key Header

All Plex API requests require a valid subscription key header. The request header X-Plex-Connect-Api-Key is a subscription key that provides access to the API. You can obtain your API key through the Plex Developer Portal.

If you do not include the subscription key header in an API request or provide an invalid subscription key, you receive the following response:

{
   "code": "REQUEST\_NOT\_AUTHENTICATED"
   "message": "The request could not be authenticated."
}

Tenant Id Header / (Multi PCN Access)

Plex API requests are performed in the context of a single default tenant (also called an entity or PCN). The request header X-Plex-Connect-Tenant-Id can be used to execute the request for a tenant other than your default tenant. The header value must be a tenant ID.


Customer Id Header

The request header X-Plex-Connect-Customer-Id can be used to execute the request for a different tenant other than your default tenant. The header value must be a PCN value.

If you do not have access to the requested tenant, you will receive the following response:

{
   "code": "REQUEST\_NOT\_AUTHENTICATED"
   "message": "The request could not be authenticated."
}

URL structure

Managed endpoints have this structure:

  https://[tier.]connect.plex.com/{collection}/{version}/{resource}[/{resource id}]?[filters]

“Tier” represents the Product or Test environment.

Example for Production Environment:

   https://connect.plex.com/mdm/v1/employees?lastName=smith

Example for Test Environment:

   https://test.connect.plex.com/mdm/v1/employees?lastName=smith

List Query String Parameters

GET method APIs use query string / URL Parameters.

To use multiple values for a list query string parameter, construct the URL with multiple instances of the query string parameter and its value pair.
For example, a query string parameter ID that can accept a list of values could have a URL for the request that looks like this:

   https://?Id=value1&Id=value2&Id=value3. 

In this example, three different values are provided for the Id query string parameter, and the request uses the three parameters that are listed. 

Methods such as PUT and POST use Request Body parameters.


Call the APIs

Using "Try-It" from the developer portal

If you have a Plex API developer account, you can test Plex APIs directly within the Plex developer portal using Try It. This functionality only works for GET endpoints, and not any other API methods.

  1. Log in to the Developer Portal and go to the APIs page.
  2. Click the API operation that you would like to test.
  3. Click Try It to view its details, such as the resource URL and the request body.
  4. After the Request URL, an Apps Dropdown appears that has a list of apps created by you. Select one of the following.
  5. Click Send request.
  6. The API request sends and the Response Tab updates with the response.
  7. After a successful response, you can use the API. Update your case in ServiceCloud to confirm you can access the API.  

Calling APIs from a third-party environment

Users can use third-party apps such as postman, Thunder client, paw, Testfully for calling methods other than "GET" API endpoints or can use the command line as well to call on API. 

Users need to ensure that the following details need to be mentioned in the HTTP request header;

  1. In the Developer Portal, go to the APIs page.
  2. Click the API operation that you would like to test.
  3. Click a resource to view its details, including the resource URL and the request body.
  4. After the Request Body, in the API Key field, click Set.
    1. For Name, type X-Plex-Connect-Api-Key.
    2. For Value, type your Customer Key. (You can retrieve this from the App that you created. See Obtain API credentials.)
    3. Select Header.
    4. Click Ok.
  5. Click Send this request.
  6. The API request is sent. The page will update with the response.
  7. After a successful response, you are ready to use the API.

Dates and Times

Coordinated Universal Time (UTC)

Use UTC or UTC+Offset standard data and time formats.


Format String 

Use the following format for any date or time input parameters:

YYYY-MM-DDThh:mm:ss.fffffffZ 

Symbols

YYYY   -->   Four-digit year (required)

MM     -->   Two-digit month (01 through 12, required)

DD      -->   Two-digit day of the month (01 through 28/29/30/31, required)

T         -->   Constant char separator between date and time components (required)

hh      -->   Two-digit hour (00 through 23, required)

mm    -->   Two-digit minute (00 through 59, required)

ss       -->   Two-digit second (00 through 59, optional)

fffffff  -->   Fractional digits of a second (0 to 7 digits, optional)

Z        -->   Constant char designation for UTC a.k.a. "Zulu Time" (required)  

The following also applies:

The following is not supported:


Range of accuracy

1999-12-31T12:34Z 

1999-12-31T12:34:56Z

1999-12-31T12:34:56.1Z 

1999-12-31T12:34:56.12Z  

1999-12-31T12:34:56.123Z  

1999-12-31T12:34:56.1234Z  

1999-12-31T12:34:56.12345Z  

1999-12-31T12:34:56.123456Z

1999-12-31T12:34:56.1234567Z 

Error Codes

200 - Success

Response code starting with 200 means query has executed successfully. 

400 - Malformed request

400 errors generally indicate that the body of the request does not match the resource being requested. 

400 - Validation failure

One or more of the parameters use an incorrect format or are omitted from the request.

401 - Request not authenticated

A 401 error can occur when you try to access the system using an expired API key, an invalid API key, or without an API key at all.
If you receive this error, verify that the X-Plex-Connect-Api-Key header is specified on the request and that the key matches the value in the Plex Developer Portal.

403 - Forbidden

A 403 forbidden client error status response code indicates that the server understood the request but refuses to authorize it. It means it's a resource that you're not allowed to access. This status is similar to 401, but in this case, re-authenticating makes no difference.

404 - Resource not found

A 404 error can occur when your application attempts to access Plex functionality using an incorrect request URL or if no data exists to return.

500 - Request processing error

500 errors are unexpected. If you can reproduce the error, submit a support ticket to Plex. Include the steps to duplicate the issue, but do not include client secrets, passwords, or subscription keys.


Glossary