Player Authorization API for Player V4

The Authorization API request is a key element in Ooyala's content protection features. This topic refers to Player V4.

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).

Authorization API Documentation

Refer to the following documentation:

Request Syntax

A request to the Authorization API has the following syntax:

[GET] /sas/player_api/v2/authorization/embed_code/{pcode}/{embed_codes}?{query_params}

Example:

http://player.ooyala.com/sas/player_api/v2/authorization/embed_code/Z5Mm06XeZlcDlfU_1R9v_L2KwYG6/44azdwNDpSWUvfd8F30d55tXY0YH9njH?codecPriority=avc&device=html5&domain=debug.ooyala.com&supported_formats=m3u8,hds&player_type=video

Route Attributes

The following table describes all attributes of the route.
Attribute Description
{pcode} The provider code
{embed_codes} Single embedcode or multiple embedcodes separated by ',' or '|'

Query String Parameters

The following table describes the query string parameters of the routes. The request can have several optional query string parameters. The only required parameter is domain.
Parameter Description Required? Values
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  
codecPriority Value for HEVC codec. No hvc (default), hec, avc, all.
player_type The type of player for content playback. A video player is capable to play both video and audio content, and an audio_only player, as the name suggests, is only capable of playing audio content. No video (default), audio_only.
device The device for which the authorization is being made. The value of this parameter is tightly coupled with the {supported_formats} parameter since some formats are not supported for specific devices. No (automatically assigned according to the device used for the request) generic_flash (default), iphone, ipad, appletv (or apple_tv), ios, chromecast, android_sdk, android_html, android_3plus_sdk, android_hls_sdk, html5, hook, dlna, generic.

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 (Widevine Classic, deprecated) wv_wvm
Adobe Access HLS faxs_hls
Microsoft Smooth Streaming smooth
M4A audio
OGG audio

If the query parameter player_type is set to audio_only, only the following three values are supported:

Format Value
AAC audio_hls
M4A audio_m4a
OGG audio_ogg

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": {
        "44azdwNDpSWUvfd8F30d55tXY0YH9njH": {
            "authorized": true,
            "code": "0",
            "message": "authorized",
            "request_timestamp": "1549578650",
            "retry": null,
            "synd_rule_failures": null,
            "require_mid_stream_check": false,
            "require_heartbeat": false,
            "restrict_devices": false,
            "is_cmaf": false,
            "streams": [
                {
                    "delivery_type": "hds",
                    "url": {
                        "format": "encoded",
                        "data": "aHR0cDovL2NmLmMub295YWxhLmNvbS80NGF6ZHdORHBTV1V2ZmQ4RjMwZDU1dFhZMFlIOW5qSC80NGF6ZHdORHBTV1V2ZmQ4RjMwZDU1dFhZMFlIOW5qSF8xLmY0bQ=="
                    }
                },
                {
                    "delivery_type": "hls",
                    "url": {
                        "format": "encoded",
                        "data": "aHR0cDovL3BsYXllci5vb3lhbGEuY29tL2hscy9wbGF5ZXIvYWxsLzQ0YXpkd05EcFNXVXZmZDhGMzBkNTV0WFkwWUg5bmpILm0zdTg/dGFyZ2V0Qml0cmF0ZT0yMDAw"
                    }
                }
            ]
        }
    },
    "user_info": {
        "ip_address": "",
        "domain": "",
        "request_timestamp": "",
        "device": "",
        "postal_code": "",
        "country": "",
        "timezone": "",
        "continent": "",
        "state": "",
        "city": "",
        "latitude": "",
        "longitude": ""
    },
    "debug_data": {
        "server_latency": "32.298190999999996",
        "request_id": "9b8e2b9d0b8c89d42078c874702e95dc",
        "user_info": {
            "request_timestamp": ""
        },
        "provider_enabled_ssl": true,
        "provider_not_use_cookies": false
    },
    "signature": "fhLQIE2H8WUxwY90xEg0wB5pcQ4jvYMU1j7cLel2J/E="
}

Elements of the Response

Among the elements returned in the response:

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