SEES Public API

The entitlement request and response are passed via a mutually authenticated SSL connection between the license server and the customer’s entitlement service.

The HTTPS URI scheme ( https://tools.ietf.org/html/rfc7230#section-2.7.2) is used to define the entitlement endpoint, and the HTTP POST request method ( https://tools.ietf.org/html/rfc7231#section-4.3.3) is used for the request. The entitlement endpoint, as well as a flag indicating back-end entitlement, is required and must be included in the policy at packaging time.

Entitlement Request

The body of the entitlement request will be a JSON object defined as shown below.

JSON entitlement request object definition

{
 "title" : "Entitlement Request",
 "type" : "object",
 "properties" : {
  "messageID" : {
   "type" : "string",
   "description" : "Unique ID for this message (GUID).  Used to confirm that the subsequent response is actually for this request."
  },
  "version" : {
   "type" : "integer",
   "description" : "Version number of the protocol, currently 1."
  },
  "requestType" : {
   "type" : "integer",
   "description" : "Request type. 1 - time based entitlement request, 2 - device registration entitlement request 3 - device bound entitlement request."
  },
  "contentID" : {
   "type" : "string",
   "description" : "Content ID (GUID) that was given to the content during packaging time."
  },
  "customerCookie" : {
   "type" : "string",
   "description" : "Customer cookie. Cookie is just arbitrary string up to 32 characters long."
  }
    },
 "required" : ["messageID", "version", "contentID"]
}

Entitlement Response

The body of the entitlement response is a JSON object.

JSON entitlement response object definition

{
  "title" : "Entitlement Response",
  "type" : "object",
  "properties" : {
    "messageID" : {
    "type" : "string",
    "description" : "Unique ID from the Entitlement Request message.
      Must match, or entitlement will be denied."
  },
  "version" : {
    "type" : "integer",
    "description" : "Version number of the protocol; must be <= the version number
      from the Entitlement Request message."
  },
  "isAllowed" : {
    "type" : "boolean",
    "description" : "Grant the license or not."
  },
  "epTokenURL" : {
    "type" : "string",
    "description" : "ExpressPlay Token URL"
  },
  "error" : {
    "type" : "integer",
    "description" : "An error number produced by the entitlement server.
      Will be passed to the client as the 'code' field of the server error response."
  },
  "errorText" : {
    "type" : "string",
    "description" : "Additional error information produced by the entitlement server.
      Will be passed to the client as the 'text' field of the server error response."
  },
  "required" : ["messageID", "version", "isAllowed", "epTokenURL"]
}