Player Authorization API for Player V3

The Authorization API request is a key element of Ooyala's content protection features.

Note: This API applies to Player V3. For information on the Player Authorization API for Player V4, see Player Authorization API for Player V4.
A request to the Authorization API has the following syntax:


Route Attributes

The following table describes all attributes of the route.
Attribute Description
pcode Your provider code
ListOfCommaSeparatedEmbedCodes Embed codes (content IDs or asset IDs) must be separated by commas in this list.

Query String Parameters

The following table describes the query string parameters of the routes. The request can have several optional query string parameters following in suit. The only required parameter is domain.
Parameter Description Required?
domain Domain of the player embed. Yes
timestamp Timestamp in which the request was made (epoch time).

Default: Time request received by server

supported_formats List of comma-separated values indicating supported formats. The value of this parameter is normally tightly coupled with the device type, since support for formats is limited by device.

Valid Values: Shown in table below

device List of comma-separated devices for playback.

Valid Values: See table below

jsonp Value of this parameter will be used as the wrapper in returning JSONP.

Default: JSON

embed_token Discussed in section "Ooyala Player Token" in the Player Developer Guide. No
auth_token Authorization token, discussed in Limiting Concurrent Streams per Viewer No

Supported Formats and Devices

The supported_formats parameter can be a list of any of the following values, separated by commas.
Format Value
DASH dash
HDS hds
HLS m3u8
MP4 mp4
Akamai HD akamai_hd
Fairplay HLS fps
Widevine HLS wv_hls
Widevine MP4 wv_mp4
Widevine WVM wv_wvm
Adobe Access HLS faxs_hls
MicroSoft Smooth Streaming.
Note: For smooth streaming, device (see below) must be GENERIC.
The device parameter can be a list of any of the following values, separated by commas:
  • IPAD
  • HTML5

Response from the Authorization API

When the caller makes an authorization request, the Authorization API responds to the caller with a JSON array indicating the authorization status for each of the embed codes included in the list in question. The following is a sample response from the Authorization API:

         "continent":"NORTH AMERICA",

Elements of the Response

The significant portions of the response are in boldface type in the sample. These parts of the response are:

  1. debug_data is used only for debugging data. It can change at any time.
  2. signature in the response is used to ensure that the response has not been tampered with by a 3rd party.
  3. streams are included if the embed code was authorized, including the base64 encoded url to access those streams. Each stream can return with an authorization result of:
    • "authorized"
    • “unauthorized parent"
    • "unauthorized domain"
    • "unauthorized location"
    • "unauthorized device"
    • “current time is before the flight start time" (before flight start time)
    • "current time is after the flight end time" (after flight end time)
    • "current time is outside any availability period" (outside recurring flight times)
    • "this is not a recognized embed code"
    • "invalid signature" (invalid signature in the request, potentially when using token based playback)
    • "missing parameters" (required parameters are missing)
    • "missing rule set" (when authorizing using a rule set rather than a syndication group)
    • “unauthorized” (this message rarely, if ever, used, in favor of more specific messages)
    • "missing pcode",
    • "invalid token" (error code for token based playback and Adobe Pass)

For response that includes a Widevine stream, the additional property widevine_server_path is returned. This value should be passed along with the stream URL to the playback SDKs for obtaining the Widevine license and decrypting the token.


For per-viewer concurrent stream limits, additional properties are returned, as detailed in Limiting Concurrent Streams per Viewer.