Player Authorization API for Player V4

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

Note: This API applies to Player V4. For more information on the Player Authorization API for Player V3, see Player Authorization API for Player V3 (Deprecated).
A request to the Authorization API has the following syntax:
[GET]/sas/player_api/v2/authorization/embed_code/pcode/ListOfCommaSeparatedEmbedCodes?query_string_paramters

Example:

http://player.ooyala.com/sas/player_api/v2/authorization/embed_code/R0Y3Y6HtBEQtRUoC55GY8DTF4pGA/44azdwNDpSWUvfd8F30d55tXY0YH9njH?device=html5&domain=www.ooyala.com&supportedFormats=m3u8%2Cmp4		
	

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

No
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

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

Default: JSON

No
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. A stream for each format specified in the supported_formats parameter is returned. If the supported_formats parameter is blank, streams for all available formats are returned.
Format Value
DASH dash
HDS hds
RTMP RTMP
HLS m3u8
MP4 mp4
Akamai HD akamai_hd
Fairplay HLS fps
Widevine WVM wv_wvm
Adobe Access HLS faxs_hls
MicroSoft Smooth Streaming smooth

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. The following is a sample response from the Authorization API:

{ 
   "authorization_data":{ 
      "NiMmNsODprSK3Uo3-EIBA5bbhuThv0Rn":{
         "authorized":true,
         "code":"0",
         "message":"authorized",
         "request_timestamp":"1460678999",
         "retry":null,
         "synd_rule_failures":null,
         "require_heartbeat":false,
         "restrict_devices":false,
         "streams":[ { 
            "delivery_type":"dash",
            "url":{ 
               "format":"encoded", 
               "data":"aHR0cDovL3NzLmMub295YWxhLmNvbS9vbmRlbWFuZC9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi8xLmlzbS9NYW5pZmVzdA==" 
               } ,
               "drm": {
                  "widevine" :{
                     "la_url":"https://player.ooyala.com/sas"
                              } ,
                  "playready":{
                          }
                       }
                    }
              }, { 
             "delivery_type":"hls",
             "url":{ 
                "format":"encoded", 
                "data":"aHR0cDovL3BsYXllci5vb3lhbGEuY29tL3BsYXllci9pcGhvbmUvTmlNbU5zT0RwclNLM1VvMy1FSUJBNWJiaHVUaHYwUm4ubTN1OD9zZWN1cmVfaW9zX3Rva2VuPU5sUlZRVmxyVTBRemVIUTFaakpCUkhoWFVHcFpkMUpPVjJGaVRXdDBVbTVLUlhoa2NGTkhRbGhYV1RKWFowSjVkV2NyVVdkR2FqRjZRaXRwQ2pGaFVWRk5Va3RaVm1aSmIwTldUbVp3UmxwR016VllTMFJuUFQwSw==", "ios_token_expire":1460679000 
                }, 
                "drm": {
                   "fairplay" :{
                      "la_url":"https://player.ooyala.com/sas","certificate_url":"https://blah" 
                               }
                       }
               },{ 
             "delivery_type":"smooth",
             "url":{ 
                "format":"encoded", 
                "data":"aHR0cDovL3NzLmMub295YWxhLmNvbS9vbmRlbWFuZC9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi8xLmlzbS9NYW5pZmVzdA==" }
                }, { 
             "delivery_type":"hds",
             "url":{ 
                "format":"encoded", 
                "data":"aHR0cDovL2FrLmMub295YWxhLmNvbS9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbl8xLmY0bQ==" }
                },{ 
                "video_bitrate":4500,
                "profile":"baseline",
                "width":1280,
                "height":960,
                "framerate":"30.0",
                "video_codec":"h264",
                "audio_bitrate":128,
             "delivery_type":"rtmp",
             "url":{ 
                "format":"encoded", 
                "data":"cnRtcDovL2NwNzY2NzcuZWRnZWZjcy5uZXQvb25kZW1hbmQvcy9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi9ET2NKLUZ4YUZyUmc0Z3RERXdPalEwWXpvd09ERTdKOA==" }
                },{ 
                "video_bitrate":4500,
                "profile":"baseline",
                "width":1280,
                "height":960,
                "framerate":"30.0",
                "video_codec":"h264",
                "audio_bitrate":128,
             "delivery_type":"mp4",
             "url":{ 
                "format":"encoded", 
                "data":"aHR0cDovL2FrLmMub295YWxhLmNvbS9OaU1tTnNPRHByU0szVW8zLUVJQkE1YmJodVRodjBSbi9ET2NKLUZ4YUZyUmc0Z3RERXdPalEwWXpvd09ERTdKOA==" 
                }
             }
          ]
       }
   },
   "user_info":{ 
      "ip_address":"198.38.13.132", 
      "domain":"test.com", 
      "request_timestamp":"1460678999", 
      "country":"US", "timezone":-7.0, 
      "continent":"NORTH AMERICA" 
               },
   "debug_data":{ 
   "server_latency":"43.505105",
   "request_id":"54e3b3c4933120b8b7d6fb6382c5edb9",
   "user_info":{ 
      "request_timestamp":"1460678999" }
          },
          "auth_token":"c1hIVDBBK3hKNVRYV01vZVowNnNLZmJJQWcxa2FhMDc4SXBZektGVXFjdnI2VGVOeFNVTjZPV1Y4ZmJNCmxXTTNQdVo1NUhIZnlYbmN6TDduM1RGSFNqUGhDTHdscnUxbG9iK3JzWGRsT21JWFRCUnRDVzBuTjU1RQp1cEYvMXd6aGhvSlJ0TllSZFlTSHZZd2RqN1BxV0MzSEY4L25DOW9WS3JZOStKTGxoQmVHN0lidFV0QkQKcDBrSkVieFUwcHZuV2tNM1ZBNEF3ZXRYNWh6Nzd3ekFwSm5LRlNFWUJ3SWVlVmZ3ODA3MGZSamQ3czZlCmx3amxVR1FwNVhEbzAyK0wK",
          "auth_token_expires":1460684999,
          "heartbeat_data":{},
          "signature":"HBZJC39psbeF30Do6WHQJQRIkA2qRWzcT3gUcKGGnXg="
}	

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 per-viewer concurrent stream limits, additional properties are returned, as detailed in Limiting Concurrent Streams per Viewer.

해당 내용이 도움 되었습니까?