The SecureHD Policy Editor API

The SecureHD Policy Editor (SPE) serves as a “one stop shop” solution for the configuration and application of various security services for your Akamai HD Network media content, allowing you to apply Token Authorization, Content Targeting (GEO Protection), Media Encryption and Player Verification protection. Luna Control Center provides a graphical interface to SPE.

The SPE REST API provides a RESTful, HTTP-based API with simple XML or JSON objects and informative HTTP messages for customers needing programmatic control of their SPE security settings. You can easily use it with most programming languages.

Input/Output Formats

The SPE API supports multiple formats of input and output for for use in call requests (e.g., for response output as well as inclusion of POST/PUT Body content).

Response Output

  • XML (default): Issuing API calls using the standard syntax for calls revealed in this documentation will return output in XML format. This API adheres to a fixed XML schema.

  • JSON: JSON output can be set by appending .json to the end of any of the API call syntax revealed in this documentation.

Output examples in this document are revealed in XML (default).

Input (POST/PUT Body Content)

Various calls may require that you pass additional content to the API (e.g., include a POST/PUT Body component). Based on your selected format, ensure that you establish the appropriate content type in the HTTP header:

  • XML: application/xml
  • JSON: application/json

In addition, examples for POST/PUT Body content in this document are revealed in the API default, which is XML. When consulting these examples, ensure that you are using proper formatting, if JSON is your chosen input format. For example, if an XML example in this guide reveals a value as <tag>input</tag>, the JSON equivalent would be "tag": "input".

NOTE: Regarding POST/PUT Body contents, if a specific component is not required, include its tag/pair in the context of a POST/PUT Body, but leave it empty (e.g., provide no argument: <option></option>, "option": "").

Variable Values in Input/Output Syntax

Throughout this document, variable values will be revealed, enclosed in braces "{ }". Unless otherwise noted, do not include these characters; they only serve to mark the value as variable.

Security Service Support and Prerequisites

Certain services are not supported for use with certain media formats (or combinations of services are not supported). Prior to using the API, please review the SecureHD Policy Editor–Support Matrix document.

In addition, each individual SecureHD Policy Editor security service requires various prerequisite conditions be met prior to enabling within a policy. Complete details on these prerequisites, along with detailed information on the use of each service, can be found in the SecureHD Policy Editor–User Guide.

Country, Region and DMA Codes

Throughout the SPE API you may be confronted with tags/pairs that require you to provide geographic (geo) “codes”. These apply to integer/established values that represent a specific geographic region (e.g., used to allow/block access to content via Content Targeting protection). As a point of reference for these codes, you can consult Akamai Luna Control Center and access the EdgeScape Data Codes page (Support ⇒ User and Developer Guides ⇒ EdgeScape ⇒ Data Codes). Once here, select the relevant link for your desired code type:

  • Country Codes: “Country Code”

  • Region Code: “State/Region Code”

  • DMA: “Designated Market Area” (DMA® is a registered service mark of The Nielson Company, all rights reserved.)

API Summary

The following table provides details for all of the API’s operations:

Action Operation Endpoint Description
Policies
List Policies GET /config-media-security/v1/security List all policies for the currently active account (i.e., those associated with the current User ID/Password).
Create a Policy POST /config-media-security/v1/security Create a new security policy.
Get a Policy GET /config-media-security/v1/security/{policyID} Returns detailed information pertaining to the named policy (i.e., as defined via the policyID variable).
Modify a Policy PUT /config-media-security/v1/security/{policyID} Used to edit the specified policy (defined as the policyID variable), via an accompanying PUT Body component.
Mark a Policy for Deletion DELETE /config-media-security/v1/security/{policyID} This will “mark” the specified policy for delete. (i.e., as defined via the policyID variable). To formally process the delete, it must be “promoted,” which is accomplished via the Remove a Policy operation.
Get Policy per Environment GET /config-media-security/v1/security/{policyID}/{environment} Returns detailed information pertaining to the named policy (i.e., as defined via the policyID variable). Additionally, it filters results by desired Akamai environment, either Staging or Production.
Clone a Policy POST /config-media-security/v1/security/{policyID}/clonePolicy Will create a clone of the policy input as as the policyID, and save it to the Staging network.
Promote a Policy PUT /config-media-security/v1/security/{policyID}/promote Once a policy is created, it must be promoted from the Akamai Staging environment to the Production environment, for inclusion in a policy/HD configuration assignment. Use this call to promote the policy set as the policyID variable.
Remove a Policy DELETE /config-media-security/v1/security/{policyID}/promoteDelete Deletes a specified policy (as defined via the policyID variable) from production and staging networks (i.e., if it is marked as deleted on the Staging environment).
Restore a Policy Deletion PUT /config-media-security/v1/security/{policyID}/revertDelete To delete a policy, it must first be “marked for delete” prior to the formal delete operation (which is accomplished via the Mark a Policy for Deletion operation). Use this operation to revert the “delete” marker and return the policy to the Staging environment.
Restore a Policy Edit PUT /config-media-security/v1/security/{policyID}/revertEdit If you have recently performed edits to a policy, but have not promoted it to the Production Akamai environment, you can use this call to revert the policy back to its pre-edited state.
HD Configuration/Digital Properties
Get an HD Config Policy GET /config-media-security/v1/security/live/{domain}/policy Use this operation to gather information regarding policies in place for a specified HD configuration (i.e., set as the domain variable in the call). This will return results for both Staging and Production environments.
Modify an HD Config Policy PUT /config-media-security/v1/security/live/{domain}/policy Use this operation to create/update a policy assignment between a specified HD configuration (i.e., the domain variable in the call syntax), and one or more policies, which are defined in an accompanying PUT Body component.
Get an HD Config Policy per Environment GET /config-media-security/v1/security/live/{domain}/policy/{environment} Use this operation to gather information regarding policies in place for a specified HD configuration domain, within a specified Akamai environment. (i.e., either Staging or Production).
List Policy Assignments GET /config-media-security/v1/security/live/{policyID}/policyassignments Returns policy assignment information for the specified policyID, for both the Staging and Production environments.
Get a Policy Assignment GET /config-media-security/v1/security/live/{policyID}/policyassignments/{environment} Returns policy assignment information for the specified policyID, within a particular Akamai environment (i.e., either Staging or Production).
Promote a Policy Assignment PUT /config-media-security/v1/security/live/{policyID}/policyassignments/promote If you have created or edited a policy assignment, you would use this call to promote it from the Staging Akamai environment to Production (i.e., to formally apply the protections in the policy to end-user accessible content housed in the HD configuration).
Revert Promotion of a Policy Assignment PUT /config-media-security/v1/security/live/{policyID}/policyassignments/revert If you have edited a policy assignment, you can use this call to revert the policy assignment to its pre-edited state.
Security Services
List Countries GET /config-media-security/v1/security/countries Returns a list of Countries available for use in configuring the GeoProtection feature of Content Targeting.
List Designated Market Areas GET /config-media-security/v1/security/dmas Returns a list of the Designated Market Areas (DMAs) available for use in configuring the GeoProtection feature of Content Targeting. (United States only)
List Regions GET /config-media-security/v1/security/regions Returns a list of the Regions available within a selected country (e.g., states or territories) for use in configuring the GeoProtection feature in Content Targeting.
List Regions per Country GET /config-media-security/v1/security/regions/{countryCode} Returns a list of eligible Regions for a given country (i.e., as defined as the countryCode variable). For use in configuration of the GeoProtection feature of Content Targeting.
Miscellaneous
List Access Control Groups GET /config-media-security/v1/security/acgs Used to view a list of Access Control Groups accessible to the currently logged-in user account.

Usage Examples

The following sections reveal non-language-specific examples of the use of the interfaces to create a new SPE policy and assign it to an HD configuration of content to protect it. This process follows a four-phased procedure:

  1. Create a Security Policy
  2. Promote the Policy from “Staging” to “Production”
  3. Assign the Policy to a Desired HD Configuration
  4. Promote the Assignment from “Staging” to “Production”

Example #1: Creating a Security Policy

The new policy will enable Token Authorization and various Content Targeting protections (i.e., to block access to content to South Africa, specific provinces in Canada, and two specific cities in the United States, via DMA values). Additionally, Player Verification will be enabled by including a HASH of an applicable player.

POST https://[consumer_id].luna.platform.akamai.com/config-media-security/v1/security
Content-Type:application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<security-policy>
    <name>pc_test_1</name>
    <acg-id>EFG-456</acg-id>
    <description>This is a test policy</description>
    <token-auth-feature>
        <enabled>true</enabled>
        <password>456def</password>
        <transition-password>def456</transition-password>
        <enforce-on-initial-request>true</enforce-on-initial-request>
        <enforce-on-content-request>true</enforce-on-content-request>
    </token-auth-feature>
    <media-encryption-feature>
        <enabled>false</enabled>
        <percentage-coverage></percentage-coverage>
    </media-encryption-feature>
    <content-targeting-feature>
        <enabled>true</enabled>
        <geo-protection>
            <enabled>true</enabled>
            <allow-locations>false</allow-locations>
            <countries>
                <country>
                    <country-code>CA</country-code>
                </country>
            </countries>
            <dmas>
                <dma>
                    <dma-code>501</dma-code>
                </dma>
                <dma>
                    <dma-name>BatonRouge</dma-name>
                </dma>
            </dmas>
            <regions>
                <region>
                    <country-code>CA</country-code>
                    <region-code>AB</region-code>
                </region>
                    <country-code>CA</country-code>
                    <region-code>ON</region-code>
                </region>
                <region>
                    <country-code>CA</country-code>
                    <region->NS</region>
                </region>
            </regions>
            <override-ips>
                <ip>55.55.55.100</ip>
                <ip>55.55.55.101</ip>
                <ip>55.55.55.102</ip>
            </override-ips>
        </geo-protection>
        <ip-access>
            <enabled>false</enabled>
            <allow-ips></allow-ips>
            <ip-list></ip-list>
        </ip-access>
        <referral-domain>
            <enabled>false</enabled>
            <allowed-domains></allowed-domains>
        </referral-domain>
    </content-targeting-feature>
    <player-verification-feature>
        <enabled>true</enabled>
        <support-player-enabled>false</support-player-enabled>
        <reset-support-player>false</reset-support-player>
        <players>
            <player>cb6af0d91a7f824238551b092e705637947a7f1e</player>
        </players>
        <TTL>72h</TTL>
    </player-verification-feature>
</security-policy>

Tag/Pair Descriptions

The tags/pairs used in the POST Body content are described in the sections that follow.

General

Tag/Pair Name Type Description
name String This is the name that will be applied to the policy. Duplicate policy names are not supported. Each new policy must be created with a unique policy name.
acg-id String Used to specify an existing Access Control Group, applicable to your specific instance of SPE.
description String (Optional) Used to define a description of the policy for identification purposes.

Token Authorization

Tag/Pair Name Type Description
enabled Boolean True/False: Determines if Token Authorization is enabled/disabled.
password String The Primary Password established for this protection. If incorporating this protection, this is a required tag set. This must be in hexadecimal format and consist of an even number of characters.
transition-password String The Transition Password value to be set, if desired. This must be in hexadecimal format and consist of an even number of characters.
enforce-on-initial-request Boolean True/False: Determines if the Enforce URL Token for Initial Request option is enabled/disabled.
enforce-on-content-request Boolean True/False: Detrmins if the Use Cookie Tokens to Protect Content/Segment Request option is enabled/disabled.

Media Encryption

Tag/Pair Name Type Description
enabled Boolean True/False: Determines if Media Encryption is enabled/disabled.
percentage-coverage Integer The percentage of encryption that should be applied. Applicable values include 1–100, or Auto to allow SPE to determine the appropriate level.

Content Targeting

Tag/Pair Name Type Description
enabled Boolean True/False: Determines if Content Targeting is enabled/disabled.
geo-protection
enabled Boolean True/False: Determines if Geo Protection functionality is enabled/disabled within Content Targeting.
allow-locations Boolean True/False: Defines if locations specified in associated tags/pairs should be allowed/blocked from accessing content.
country-code Enumeration Used to list specific countries that are to be allowed or blocked access (i.e., based on what was set for allow-locations). Each individual country must be input using its relevant country code, and requires its own, individual tag/pair set. South Africa is to be blocked from access in this example, therefore its country code “ZA” was set.
dma-code/dma-name Enumeration Used to refine allow/block settings to specific “Designated Market Areas” (DMA). A DMA is a specific region in which the population can receive the same (or similar) Internet media offerings. Supported entries are based on the Nielsen Media Research DMA regions. A DMA can be defined using either its associated “dma-code” integer, or its API-recognized “dma-name” specific value. Each individual DMA must be defined within its own, individual dma-related tag/pair sets. For example, “501” could be designated for “New York” as a “dma-code”, and “BatonRouge” could be used as a “dma-name”.
country-code/region-code Enumeration Used to refine allow/block settings to specific regions within a named <country> (i.e., states, provinces or territories). Each individual region must be input using its relevant country code, and requires its own, individual sub-tag set. Specific regions in Canada are to be blocked from access, therefore CA is set for the country-code, and AB (Alberta), ON (Ontario) and NS (Nova Scotia) are set as individual region-codes in this example.
override-ips String Used to define individual IP Addresses or CIDR Blocks that should always be allowed access to content (i.e., regardless if they fall into an area that has been blocked). Each individual IP Address/CIDR Block needs to exist as a child, in its own id tag/pair. In this example, the IP Addresses, 55.55.55.100, 55.55.55.101, 55.55.55.102 exist within one of the regions set to be blocked, but need to have access.
ip-access
enabled Boolean True/False: Determines if the Enable IP Access Lists functionality is enabled/disabled within Content Targeting.
allow-ips Boolean True/False: Defines if IP Addresses/CIDR Blocks specified in associated tags/pairs should be allowed/blocked from accessing content.
ip-list String Used to list specific IP Addresses or CIDR Blocks that are to be allowed or blocked access (i.e., based on what was set for allow-ips). Each individual IP Address/CIDR Block needs to exist as a child, in its own id tag/pair.
referral-domain
enabled Boolean True/False: Determines if the Enable Referrer Checking functionality is enabled/disabled within Content Targeting.
allowed-domain String Used to list specific domain URLs that are to be allowed access as a referrer. Each individual domain must exist as a child, within its own domain tag/pair.

Player Verification

NOTE: Player Verification is only supported for use with Adobe HTTP Dynamic Streaming (HDS) format media.

Tag/Pair Name Type Description
enabled Boolean True/False: Determines if Player Verification is enabled/disabled.
support-player-enabled Boolean True/False: Determines whether the Enable Support Player Bypass option is enabled/disabled. When enabled, an Akamai Test Player will be set for use in testing the Player Verification security (for a period of 24 hours from the time of policy creation).
reset-support-player Boolean When set to True, this will reset the Akamai Test Player for another 24 hours. This tag/pair and support-player-enabled should not both be set to True at the same time. If you need to use this option to reset, ensure that support-player-enabled is set to False.
players String Used to list specific players for inclusion, via an SHA–256 HASH equivalent, that are to be allowed access to a referrer. Each individual player must exist as a child, in its own player tag/pair.
TTL String A “Time to Live” for the player, formatted #h/#m/#s. Once expired, the specified “Player List” player(s) will be invalidated. Input a number followed by h for hours, m for minutes or s for seconds. This time begins once the policy/hd configuration association is saved. Note that d (“days”) is not supported for use when establishing a TTL, even though a response from this operation may show a TTL in days. Input multiples of 24 hours to denote full days (e.g., 72h to indicate three days).

Response Example

Upon successful creation of a new policy, the response will reveal a unique policyID value generated for it by the API. This value is used in various additional calls, in order to interact with this specific policy.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request-successful>
    <message>Successfully created policy: {policyID}</message>
</request-successful>

Example #2: Promoting the Policy from “Staging” to “Production”

After creation, a policy will exist in Akamai’s “Staging” environment. You must promote it from Staging to “Production” to allow access to it for use in assignment to an HD configuration of content. The policyID variable in the call syntax is the unique value returned by the API after creation of the target policy.

PUT https://[consumer_id].luna.platform.akamai.com/config-media-security/v1/security/{policyID}/promote

Response Example

After successful promotion of the policy, the response will look as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request-successful>
    <message>Successfully promoted policy: {policyID}</message>
</request-successful>

Example #3: Assigning a Policy to an HD Configuration

With a policy promoted to Production, it can now be assigned to an HD configuration of content. This example reveals the assignment of two separate SPE policies to a single HD Configuration. The domain variable in the initial call syntax is the digital property that represents the HD configuration (typically the name of an HD configuration file, minus the .xml extension).

PUT https://[consumer_id].luna.platform.akamai.com/config-media-security/v1/security/live/{domain}/policy
Content-Type:application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<security-policy-assignment>
    <rules>
        <rule>
            <policy-id>2</policy-id>
                <path>/z/...</path>
                <start-time>01/01/2012 12:00 AM</start-time>
                <end-time>12/31/2012 11:00 PM</end-time>
        </rule>
        <rule>
            <policy-id>5</policy-id>
                <path>/z/...</path>
                <start-time>01/02/2012 12:00 AM</start-time>
                <end-time>12/30/2012 11:00 PM</end-time>
        </rule>
    </rules>
</security-policy-assignment>

Tag/Pair Descriptions

The tags/pairs used in the POST Body content are described below.

Tag/Pair Name Type Description
policy-id String The unique policyID value associated with the policy to be applied to the HD configuration: 2 for the first assignment, and 5 for the second in this example.
path String Input the path value that will point to the content in the target HD configuration that is to be protected by the policy (the path that leads to the domain value set in the call): /z/... in both assignments in this example.
start-time String Used to configure a starting date/time of validity for the policy assignment. Input values in the format, MM/DD/YY HH:MM AM or PM. Values input for a time must be rounded up to the hour; individual minute entries are not supported. Additionally, this can be left open to apply no Start Time by setting an asterisk (*) as its value. In this example, 01/01/12 12:00 AM is set for the first assignment and 01/02/12 12:00 AM for the second.
end-time String Supports the same input as start-time, in order to establish an end point of validity for the assignment.

Response Example

Upon successful assignment of the policy, the response would look as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request-successful>
    <message>Successfully updated the policy assignment for DP: {domain}</message>
</request-successful>

Example #4: Promoting a Policy/HD Configuration Assignment

Once an assignment between one or more security policies and an HD configuration is generated, it will exist in Akamai’s “Staging” environment (i.e., to allow for testing, if desired). To apply the protection(s) to end-user accessible content, you need to promote the assignment to Akamai’s Production environment. The policyID variable is the unique ID for a policy that was included within the policy/HD configuration assignment. If multiple polices were included in the assignment, multiple instances of this call would be required, one for each policy included.

PUT https://[consumer_id].luna.platform.akamai.com/config-media-security/v1/security/live/{policyID}/policyassignments/promote

Response Example

With a successful promotion, the response output will look as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request-successful>
    <message>Successfully promoted policy assignment: {policyID} to production</message>
</request-successful>

Other SPE Interfaces

Complete SPE functionality can be accessed via Akamai Luna Control Center (i.e., not all SPE functionality is accessible via the API). Complete instructions on the use of the UI component are covered in the Akamai SecureHD Policy Editor–User’s Guide.


Last modified: 12/13/2016