ÃÛ¶¹ÊÓƵ

Requirements

Risks

Use a registered application with REST API v2 scope.

Risks triggering HTTP 401 "Unauthorized" error responses, overloading system resources and increasing latency.

Store the client credentials in persistent storage and reuse them for every access token request.

Risks authentication loss when the client credentials are regenerated.

Store the access tokens in persistent storage and reuse them until they expire — do not request a new token for every REST API v2 call.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Requirements

Risks

Retrieve the configuration response only when requiring to prompt the user to select their MVPD (TV provider) prior to the Authentication Phase.

There is no need to retrieve the configuration response when:

• The user is already authenticated.
• The user is offered temporary access.
• The user authentication has expired, but the user can be prompted to confirm they are still a subscriber of the previously selected MVPD.

Risks overloading system resources and increasing latency.

Store the user's Pay TV provider (MVPD) selection in persistent storage to use it in all subsequent phases:

• From configuration response store the user selected MVPD "id".
• From configuration response store the user selected MVPD "displayName".
• From configuration response store the user selected MVPD "logoUrl".

Risks overloading system resources and increasing latency.

Requirements

Risks

Start the polling mechanism under the following conditions:

Authentication performed within the primary (screen) application

• The primary (streaming) application should start polling when the user reaches the final destination page, after the browser component loads the URL specified for the "redirectUrl" parameter in the Sessions endpoint request.

Authentication performed within a secondary (screen) application

• The primary (streaming) application should start polling as soon as the user initiates the authentication process—right after receiving the Sessions endpoint response and displaying the authentication code to the user.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Stop the polling mechanism under the following conditions:

Successful authentication

• The user's profile information is successfully retrieved, confirming their authentication status, therefore polling is no longer needed.

Authentication session and code expiry

• The authentication session and code expire, the user must restart the authentication process, and polling using the previous authentication code should be stopped immediately.

New authentication code generated

• If the user requests a new authentication code, then the existing session is invalidated, and polling using the previous authentication code should be stopped immediately.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Configure the polling mechanism frequency under the following conditions:

Authentication performed within the primary (screen) application

• The primary (streaming) application should poll every 3-5 seconds.

Authentication performed within a secondary (screen) application

• The primary (streaming) application should poll every 3-5 seconds.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Store parts of the user's profile information in persistent storage to improve performance and minimize unnecessary REST API v2 calls.

Caching should focus on the following profiles response fields:

mvpd

• The client application can use this to keep track of the user's selected TV provider and continue to use it further during Preauthorization or Authorization Phases.
• When the current user profile expires, the client application can use the remembered MVPD selection and just ask the user to confirm.

attributes

• Used to personalize the user experience based on different user metadata keys (e.g., zip, maxRating, etc.).
• User metadata becomes available after the authentication flow completes, therefore the client application does not need to query a separate endpoint to retrieve the user metadata information, as it is already included in the profile information.
• Certain metadata attributes may be updated during the Authorization Phase, depending on the MVPD (e.g., Charter) and the specific metadata attribute (e.g., householdID). As a result, the client application may need to query the Profiles APIs again after authorization to retrieve the latest user metadata.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Requirements

Risks

Use preauthorization decisions for content filtering and never for playback decisions.

Risks breaching contractual agreements between Programmer, MVPDs and ÃÛ¶¹ÊÓƵ.

Risks bypassing our monitoring and alerting systems.

Handle the enhanced error codes appropriately and utilize the action field to determine the necessary remediation steps.

Only a limited number of enhanced error codes warrant a retry, while most require alternative resolutions as specified in the action field.

Ensure that any retry mechanism implemented for retrieving preauthorization decisions does not result in an endless loop and that it limits retries to a reasonable number (i.e., 2-3).

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Cache successful permit decisions in memory to improve performance and minimize unnecessary REST API v2 calls, as subscription updates while the application is running are infrequent.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Requirements

Risks

Obtain authorization decisions before playback — regardless if a preauthorization decision exists.

Allow streams to continue uninterrupted even if the media token expires during playback and request a new authorization decision containing a (fresh) media token when the user makes their next playback request, regardless it is for the same or a different resource.

Live streams running for extended periods of time may choose to request a new authorization decision following video operations such as pausing content, initiating commercial breaks, or modifying asset-level configurations when the MRSS undergoes changes.

Risks breaching contractual agreements between Programmer, MVPDs and ÃÛ¶¹ÊÓƵ.

Risks bypassing our monitoring and alerting systems.

Handle the enhanced error codes appropriately and utilize the action field to determine the necessary remediation steps.

Only a limited number of enhanced error codes warrant a retry, while most require alternative resolutions as specified in the action field.

Ensure that any retry mechanism implemented for retrieving authorization decisions does not result in an endless loop and that it limits retries to a reasonable number (i.e., 2-3).

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Requirements

Risks

Implement the logout API to allow users to manually sign out, terminating their authenticated profile and follow the REST API v2 action name specified for each removed profile:

• For MVPDs supporting a logout endpoint the client application requires to navigate to the provided "url" in a user-agent.
• For "appleSSO" type profiles, the client application requires to guide the user to also log out from the partner level (Apple’s system settings).

Risks client application malfunction due to missing support on client application side.

Requirements

Risks

Send the Authorization header for every REST API v2 request.

Risks triggering HTTP 401 "Unauthorized" error responses, overloading system resources and increasing latency.

Send the AP-Device-Identifier header for every REST API v2 request.

Even when the request originates from a server on behalf of a device, the AP-Device-Identifier header value must reflect the actual streaming device identifier.

Risks triggering HTTP 400 "Bad Request" error responses, overloading system resources and increasing latency.

Send the X-Device-Info header for every REST API v2 request.

Even when the request originates from a server on behalf of a device, the X-Device-Info header value must reflect the actual streaming device information.

Risks being classified as originating from an unknown platform and treated as insecure, becoming subject to more restrictive rules, such as shorter authentication TTLs.

Additionally, some fields, such as the streaming device connectionIp and connectionPort, are mandatory for features like Spectrum’s Home Base Authentication.

Compute and store a stable device identifier that does not change across updates or reboots for the AP-Device-Identifier header.

For platforms without a hardware identifier, generate a unique identifier from application attributes and persist it.

Risks authentication loss when the device identifier changes.

Ensure you are sending only REST API v2 expected parameters and headers.

Risks triggering HTTP 400 "Bad Request" error responses, overloading system resources and increasing latency.

Requirements

Risks

Handle the enhanced error codes appropriately and utilize the action field to determine the necessary remediation steps.

Only a limited number of enhanced error codes warrant a retry, while most require alternative resolutions as specified in the action field.

Most enhanced error codes listed in the Enhanced Error Codes - REST API V2 documentation can be prevented entirely if correctly handled during development phase before launching the application.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Risks client application malfunction due to missing handling of the enhanced error codes — causing unclear error messages, improper user guidance, or incorrect fallback behavior.

Differentiate between handling HTTP error responses (e.g., 400, 401, 403, 404, 405, 500) and success responses (e.g., 200, 201) that contain enhanced error codes payloads, as discussed above.

Only a limited number of HTTP error codes warrant a retry, while most require alternative resolutions.

Most HTTP error responses can be prevented entirely if correctly handled during development phase before launching the application.

Risks overloading system resources, increasing latency, and potentially triggering HTTP 429 "Too Many Requests" error responses.

Risks client application malfunction due to missing handling of the enhanced error codes — causing unclear error messages, improper user guidance, or incorrect fallback behavior.

Requirements

Risks

Develop and test the application using the official ÃÛ¶¹ÊÓƵ Pass Authentication non-production environments:

• Prequal-Production
• Release-Staging

Perform thorough quality assurance (QA) in these environments before launching to Release-Production.

Client applications must not proceed to Release-Production without first completing end-to-end validation in non-production environments.

Risks launching with critical and major defects.

Lacking a short and efficient debugging path can hinder ÃÛ¶¹ÊÓƵ Support and Engineering from intervening quickly.

Practices

Risks

Proactively check access token validity and refresh it when expired.

Ensure that any retry mechanism for handling HTTP 401 "Unauthorized" errors first refreshes the access token before retrying the original request.

Risks triggering HTTP 401 "Unauthorized" error responses, overloading system resources and increasing latency.

Practices

Risks

Store the configuration response in memory or persistent storage for a short period of time (e.g. 3-5 minutes) to improve performance and minimize unnecessary REST API v2 calls.

Risks overloading system resources and increasing latency.

Practices

Risks

Validate authentication code submitted through user input on the secondary (2nd) application (screen) before calling /api/v2/authenticate API under the following conditions:

Authentication performed within secondary (screen) application with preselected mvpd

• Make use of Resume authentication session - POST /api/v2/{serviceProvider}/sessions/{code}

Authentication performed within secondary (screen) application without preselected mvpd

• Make use of Retrieve authentication session - GET /api/v2/{serviceProvider}/sessions/{code}

The client application would receive an error if the provided authentication code was typed wrong or in case the authentication session would be expired.

Risks various error responses and work flow issues during authentication.

Ensure client application can handle multiple profiles by either prompting the user to select a profile or applying custom logic, such as automatically selecting the profile with the longest validity period.

Risks client application malfunction due to missing support on client application side.

Support non-basic flows in case the client application business requires:

• Degraded access flows (premium feature)
• Temporary access flows (premium feature)
• Single sign-on access flows (standard feature)

Risks creating a less than ideal user experience.

Practices

Risks

Display clear user feedback if a preauthorization decision is denied, using messaging provided by MVPDs or ÃÛ¶¹ÊÓƵ via enhanced error codes.

Risks creating a less than ideal user experience.

Practices

Risks

Validate media tokens using the Media Token Verifier library.

Risks fraud schemes such as stream ripping.

Display clear user feedback if an authorization decision is denied, using messaging provided by MVPDs or ÃÛ¶¹ÊÓƵ via enhanced error codes.

Risks creating a less than ideal user experience.

Practices

Risks

Avoid automatically (programmatically) calling the logout API in scenarios like denied preauthorization or authorization, as the logout API should only be invoked in response to a direct user request.

Risks confusing the user that the authentication is failing.

Practices

Risks

Reuse code from REST API v1 for computing the device identifier and device information with minor adjustments, but ensure you are sending only REST API v2 expected parameters and headers.

Reuse code from REST API v1 for calling the DCR API to retrieve an access token.

-

Practices

Risks

Ensure the following basic flows are tested across devices and platforms:

Authentication flows

• Primary application (screen) authentication scenario
• Secondary application (screen) authentication scenario

(Optional) Preauthorization flows

• Test permit decisions scenario
• Test deny decisions scenario

Authorization flows

• Test permit decisions scenario
• Test deny decisions scenario

Logout flows

Additionally, test other access flows, if applicable:

• Degraded access flows (premium feature)
• Temporary access flows (premium feature)
• Single sign-on access flows (standard feature)

Cover top MVPD integrations (covering the most widely used providers).

Risks unforeseen failures in production, especially across less frequently tested platforms or rare flows like negative scenarios.

Use the website.

-

Phase

Mandatory

(Strongly) Recommended

Cache client credentials

Cache access tokens

Validate and refresh access tokens

Minimize configuration response retrievals

Cache configuration response

Polling mechanism fine tuning

Cache parts of profiles

Support multiple profiles

Support Degradation Feature (if business requirement)

Support TempPass Feature (if business requirement)

Support Single Sign-On Feature (if business requirement)

Cache permit preauthorization decisions

Retry mechanism fine tuning

Enhance user experience using error codes for denied preauthorization decisions

Retrieve authorization decision when user requests for playback

Retry mechanism fine tuning

Enhance user experience using error codes for denied authorization decisions

Media token validation

Implement the logout API to allow users to manually sign out

Avoid automatically calling the logout API

Mandatory

(Strongly) Recommended

Follow mandatory headers specifications

Reuse code from REST API v1

Implement enhanced error handling

Implement HTTP error handling

-