Extended TVOD support

The entitlements claim can contain TVOD entitlements for assets and season categories, as described in the Authentication section. You can include TVOD entitlements in the claim to define a user’s PPV and EST purchases.

Support for large number of TVOD entitlements

For cases when a user has more entitlements than can fit into a token, there is an additional top-level claim has_more_tvod. When this claim is included and set to true, an external entitlements service will be called if none of the token entitlements match.

Entitlements service request specification

The external entitlements service will need to accept HTTP POST operations at the configured endpoint.

POST /api/entitlements/verify HTTP/1.1
Host: https://example.entitlements.api.com
Authorization: Bearer {jwt}
Accept: application/json
Content-Type: application/json
X-Vimond-Tenant: tenantName

{
  "assetId": 123,
  "categoryId": 456
}

The entitlements service API endpoint is configurable per tenant. Vimond Operations will assist with configuring the endpoint for you. Note that the path above is just an example, the endpoint path can be anything as long as it accepts the request as shown above.

The endpoint must accept the user’s bearer token as authorization. This is the same token that is passed to the play service from the client.

The request body contains the assetId and the parent categoryId of the asset. This enables the entitlements service to check either for direct access to asset or by the categoryId (for example for season purchases).

Response format

The expected response from this service will be either 200 OK or 403 Forbidden. An OK response will be of content type application/json.

{
  "quality": "hd",
  "streamcount": "4"
}

The response body will be a JSON object containing the matching entitlement’s quality and streamcount properties. Note that an empty body is also accepted, if the entitlement does not have quality or streamcount properties associated with it.

If no quality or streamcount properties are specified, the user will get the defaults as configured in the service.

If the user is not entitled to play the asset, a 403 response is expected, and a MissingEntitlementException will be returned by the Play Service.

Disabling external checks at run-time

As a safety feature, a “circuit breaker” exists that makes it possible to disable calls to the external entitlements service at run-time, should any operations problems arise that would impact the end-user experience. If the circuit breaker is active and the has_more_tvod claim is true, the user will be granted a “fallback entitlement” and be able to play back the asset.

Note that activation of the circuit breaker is a manual decision.