Third-Party Entitlement API

The Entitlement API validates an individual user's access to a specific Nomad Media content item without requiring the user to log in directly to Nomad Media. It is commonly used to validate permissions for a VOD asset, a content item, or a Live Channel via an external third-party authentication system.

The general workflow begins when a client request arrives with a validation token granting access to the resource.

If the token is not present, or if the entitlement API returns a denial, the user is redirected back to a page on the main third-party website. If any errors occur in either the Nomad Media API or the third-party API, it is recommended to allow the user access anyway to preserve a positive user experience.

Request Structure

The typical third-party entitlement API call takes the following structure:

POST {3rd-party-url}

Authorization: Bearer abc...xyz
Content-Type: application/json

{
  "contentId": "{unique-content-id}",
  "token": "{token from client-app}"
}

JavaScript Example

async function thirdPartyEntitlementAPI(authToken) {
    const headers = new Headers();
    headers.append("Content-Type", "application/json");
    headers.append("Authorization", `Bearer ${authToken}`);

    let body = {
        contentId: "{unique-content-id}",
        token: "{token from client-app}"
    };

    const response = await fetch(`{3rd-party-url}`, {
        method: "POST",
        headers: headers,
        body: JSON.stringify(body)
    }).catch((exception) => {
        throw exception;
    });

    if (response.ok) {
        const userContext = await response.json();
        return userContext;
    }

    return undefined;
}

Python Example

import json, requests

def third_party_entitlement_api(AUTH_TOKEN: str) -> dict:

    if not AUTH_TOKEN:
        raise Exception("Authentication Token: The authentication token is invalid")

    API_URL = "{3rd-party-url}"

    HEADERS = {
        "Authorization": "Bearer abc...xyz",
        "Content-Type": "application/json"
    }

    BODY = {
        "contentId": "{unique-content-id}",
        "token": "{token from client-app}"
    }

    try:
        RESPONSE = requests.post(API_URL, headers=HEADERS, data=json.dumps(BODY))
        INFO = json.loads(RESPONSE.text)

        if RESPONSE.status_code != 200:
            raise Exception("Response returned " + str(RESPONSE.status_code))

        return INFO

    except:
        raise Exception("Search failed" + json.dumps(RESPONSE))

Response

Success — HTTP 200 OK:

{
  "id": "{unique-id}",
  "firstName": "{first-name}",
  "lastName": "{last-name}",
  "email": "{email}"
}

Failure — HTTP 403 Forbidden:

No access. The entitlement is not valid for the requested content.

Field Notes

Field	Description
`contentId`	The unique Nomad Media identifier for the specific content item or live channel. Obtain this value programmatically or via the admin UI.
`token`	The token established by the third party and sent in the client request URL. Passed through without modification.
Response `id`	The unique identifier of the customer in the third-party system. Enables correlation of the same customer across multiple experiences.