Media Security Policy API v2

Create a policy of security services and apply this policy to a Media Services Configuration to protect HDS (v1) and HLS (v1) format media.

Learn more:


Overview

The Media Security Policy (MSP) product lets you configure and apply security services for legacy streaming formats:

  • Apple HTTP Live Streaming (HLS) version 1.0
  • Adobe HTTP Dynamic Streaming (HDS) version 1.0

You can apply token authorization, encrypt content, restrict access to specific geographic regions, and make sure it reaches only the set of viewers you intend.

Get started

There are various prerequisites that must be met before you start using Media Security Policy (MSP)

You need security service permissions

Each individual security service in MSP requires an individual permission for use. This includes Token Authorization, Content Targeting, Media Encryption and **Player Verification (Adobe Flash, ONLY). These permissions are established during provisioning of your account. Contact your account representative for complete details.

You need a Media Services Configuration

Formerly referred to as an “HD Configuration”, this is a collection of settings used to target and deliver HLS 1.0 or HDS 1.0 media content. You enable MSP within this configuration and later associate it with a Media Security Policy via a policy assignment. This configuration is created using a separate tool, so it’s outside the scope of this API. You can find instructions on this process in the Media Security Policy - User Guide.

You need to understand what’s supported

Certain MSP security services are not supported for use with certain media formats, and you can’t combine some services in the same policy. Also, some of these security services have unique prerequisites. Prior to using the API, see What is supported with MSP?

How to set up a Media Security Policy in this API

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named SecureHD Policy Editor OTN, and set the access level to READ-WRITE.

This workflow can be summed up in four basic phases:

  1. Create a security policy. Use the required members to Create a Policy. The creation response includes a unique policyId. You include the policyId when promoting or modifying the policy. You can also List Policies to retrieve the policyId assigned.

  2. Promote the policy from staging to production. After you create the policy, it’s placed in the staging network, where you can verify its settings. Before you can assign your policy to a production Media Services Configuration to protect it, you must Promote a Policy to the production network.

  3. Assign the Policy to a Desired HD Configuration. Once your policy is in the production network, you can Modify a Policy Assignment per Config.

  4. Promote the Assignment from staging to production. To apply the policy’s protections to end-user accessible content, you need to Promote a Policy Assignment to Akamai’s production network.

Take a look at You should understand the MSP workflow for a detailed understanding of this workflow.

Country, region and DMA codes

Throughout this API, there are tags and pairs that require you to provide geographic (geo) codes. These are Akamai-specific integer values that represent a specific geographic region. For a list of these codes, see the EdgeScape Data Codes page in Akamai Control Center. Select the relevant link for your desired code type:

  • Country codes: “Country Code”
  • States, territories or region codes: “State/Region Codes”
  • DMA: “Designated Market Area” (DMA is a registered service mark of The Nielson Company, all rights reserved.)

Resources

Examine and manage security policies for your account.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List regions GET /config-media-security/v2/regions
List Designated Market Areas GET /config-media-security/v2/dmas
List countries GET /config-media-security/v2/countries
List policies GET /config-media-security/v2/policies
Create a policy POST /config-media-security/v2/policies
Get a policy GET /config-media-security/v2/policies/{policyId}
Modify a policy PUT /config-media-security/v2/policies/{policyId}
Delete a policy DELETE /config-media-security/v2/policies/{policyId}
Patch a policy PATCH /config-media-security/v2/policies/{policyId}
List policy assignments GET /config-media-security/v2/policies/{policyId}/assignments
List configurations GET /config-media-security/v2/configurations
List policy assignments per configuration GET /config-media-security/v2/configurations/{domain}/assignments
Create or modify a policy assignment PUT /config-media-security/v2/configurations/{domain}/assignments
Patch a policy assignment PATCH /config-media-security/v2/configurations/{domain}/assignments

List regions

Get available regions to configure a policy’s geoProtection feature for ContentTargeting. Pass in the countryCode and regionCode members unmodified. The regionName is optional during configuration.

GET /config-media-security/v2/regions

Status 200 application/json

Object type: Region

Download schema: RegionsDTO.json

Response Body:

[
    {
        "countryCode": "AU",
        "regionCode": "ACT",
        "regionName": "Australian Capital Territory"
    },
    {
        "countryCode": "AU",
        "regionCode": "NSW",
        "regionName": "New South Wales"
    },
    {
        "countryCode": "AU",
        "regionCode": "NT",
        "regionName": "Northern Territory"
    },
    {
        "countryCode": "AU",
        "regionCode": "QLD",
        "regionName": "Queensland"
    },
    {
        "countryCode": "AU",
        "regionCode": "SA",
        "regionName": "South Australia"
    },
    {
        "countryCode": "AU",
        "regionCode": "TAS",
        "regionName": "Tasmania"
    },
    {
        "countryCode": "US",
        "regionCode": "WV",
        "regionName": "West Virginia"
    },
    {
        "countryCode": "US",
        "regionCode": "WY",
        "regionName": "Wyoming"
    }
]

List Designated Market Areas

Get available dmas to configure a policy’s geoProtection feature for ContentTargeting.

GET /config-media-security/v2/dmas

Status 200 application/json

Object type: DesignatedMarketArea

Download schema: DmasDTO.json

Response Body:

[
    {
        "dmaCode": "500",
        "dmaName": "Portland-Auburn::ME,NH"
    },
    {
        "dmaCode": "501",
        "dmaName": "NewYork::CT,NJ,NY,PA"
    },
    {
        "dmaCode": "502",
        "dmaName": "Binghamton::NY"
    },
    {
        "dmaCode": "503",
        "dmaName": "Macon::GA"
    },
    {
        "dmaCode": "504",
        "dmaName": "Philadelphia::DE,NJ,PA"
    },
    {
        "dmaCode": "505",
        "dmaName": "Detroit::MI"
    },
    {
        "dmaCode": "868",
        "dmaName": "Chico-Redding::CA"
    },
    {
        "dmaCode": "881",
        "dmaName": "Spokane::ID,MT,OR,WA"
    }
]

List countries

Get available countries to configure a policy’s geoProtection feature for ContentTargeting.

GET /config-media-security/v2/countries

Status 200 application/json

Object type: Country

Download schema: CountriesDTO.json

Response Body:

[
    {
        "countryCode": "AD",
        "countryName": "Andorra",
        "continentCode": "EU"
    },
    {
        "countryCode": "AE",
        "countryName": "United Arab Emirates",
        "continentCode": "AS"
    },
    {
        "countryCode": "AF",
        "countryName": "Afghanistan",
        "continentCode": "AS"
    },
    {
        "countryCode": "AG",
        "countryName": "Antigua and Barbuda",
        "continentCode": "NA"
    },
    {
        "countryCode": "AI",
        "countryName": "Anguilla",
        "continentCode": "NA"
    },
    {
        "countryCode": "ZW",
        "countryName": "Zimbabwe",
        "continentCode": "AF"
    }
]

List policies

Get all available policies for the account.

GET /config-media-security/v2/policies

Status 200 application/json

Object type: Policy

Download schema: PoliciesDTO.json

Response Body:

[
    {
        "policyName": "Policy - All Features",
        "policyId": 1,
        "description": "Test demo policy",
        "environment": "production",
        "status": "ACTIVE_EDITED_STAGING",
        "tokenAuth": {
            "enabled": true,
            "password": "c319f970fd89b9f8c3d48e25548c793d",
            "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": true,
            "percentageCoverage": "AUTO"
        },
        "contentTargeting": {
            "enabled": true,
            "geoProtection": {
                "enabled": true,
                "mode": "ALLOW",
                "countries": [
                    {
                        "countryCode": "IN"
                    }
                ],
                "dmas": [
                    {
                        "dmaCode": "501"
                    }
                ],
                "regions": [
                    {
                        "countryCode": "US",
                        "regionCode": "CA"
                    }
                ],
                "overrideIps": [
                    "55.55.55.100",
                    "55.55.55.101"
                ],
                "geoRedirectOnDenyEnabled": true,
                "geoRedirectOnDenyURL": "https://www.akamai.com"
            },
            "ipAccess": {
                "enabled": true,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": true,
                "denyOnIPRedirectURL": "https://www.akamai.com",
                "ips": [
                    "55.55.55.102"
                ]
            },
            "referer": {
                "enabled": true,
                "domains": [
                    "akamai.com"
                ],
                "referrerRedirectEnabled": true,
                "referrerRedirectURL": "https://www.akamai.com"
            },
            "denyAnonymousProxies": true,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": true,
            "supportPlayerEnabled": true,
            "resetSupportPlayer": false,
            "players": [
                {
                    "hash": "SAMPLEHASH",
                    "description": "Sample Player",
                    "enabled": true
                }
            ],
            "ttl": "1d",
            "email": "tst-demo@akamai.com"
        }
    },
    {
        "policyName": "Policy - All Features",
        "policyId": 1,
        "description": "Test demo policy",
        "environment": "staging",
        "status": "ACTIVE",
        "tokenAuth": {
            "enabled": true,
            "password": "478bdf12ee2e785b1c64ed818c643934",
            "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": true,
            "percentageCoverage": "30"
        },
        "contentTargeting": {
            "enabled": true,
            "geoProtection": {
                "enabled": true,
                "mode": "DENY",
                "countries": [
                    {
                        "countryCode": "IN"
                    }
                ],
                "dmas": [
                    {
                        "dmaCode": "501"
                    }
                ],
                "regions": [
                    {
                        "countryCode": "US",
                        "regionCode": "CA"
                    }
                ],
                "overrideIps": [
                    "55.55.55.100",
                    "55.55.55.101"
                ],
                "geoRedirectOnDenyEnabled": true,
                "geoRedirectOnDenyURL": "https://www.akamai.com"
            },
            "ipAccess": {
                "enabled": true,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": true,
                "denyOnIPRedirectURL": "https://www.akamai.com",
                "ips": [
                    "55.55.55.102"
                ]
            },
            "referer": {
                "enabled": true,
                "domains": [
                    "akamai.com"
                ],
                "referrerRedirectEnabled": true,
                "referrerRedirectURL": "https://www.akamai.com"
            },
            "denyAnonymousProxies": true,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": true,
            "supportPlayerEnabled": true,
            "resetSupportPlayer": false,
            "players": [
                {
                    "hash": "SAMPLEHASH2",
                    "description": "Sample Player2",
                    "enabled": true
                },
                {
                    "hash": "SAMPLEHASH",
                    "description": "Sample Player1",
                    "enabled": true
                }
            ],
            "ttl": "1d",
            "email": "demo@akamai.com"
        }
    },
    {
        "policyName": "Policy - Content Targeting",
        "policyId": 2,
        "description": "Test - Content Targeting",
        "environment": "staging",
        "status": "ACTIVE",
        "tokenAuth": {
            "enabled": false,
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": false,
            "percentageCoverage": "100"
        },
        "contentTargeting": {
            "enabled": true,
            "geoProtection": {
                "enabled": true,
                "mode": "DENY",
                "countries": [
                    {
                        "countryCode": "IN"
                    }
                ],
                "dmas": [
                    {
                        "dmaCode": "501"
                    }
                ],
                "regions": [
                    {
                        "countryCode": "US",
                        "regionCode": "CA"
                    }
                ],
                "overrideIps": [
                    "55.55.55.100",
                    "55.55.55.101"
                ],
                "geoRedirectOnDenyEnabled": false
            },
            "ipAccess": {
                "enabled": true,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": false,
                "ips": [
                    "55.55.55.102"
                ]
            },
            "referer": {
                "enabled": true,
                "domains": [
                    "akamai.com"
                ],
                "referrerRedirectEnabled": false
            },
            "denyAnonymousProxies": true,
            "denyTransparentProxies": true
        },
        "playerVerification": {
            "enabled": false,
            "supportPlayerEnabled": false,
            "resetSupportPlayer": false,
            "players": []
        }
    },
    {
        "policyName": "Policy - Media Encryption",
        "policyId": 3,
        "description": "Test - Media Encryption",
        "environment": "production",
        "status": "ACTIVE_EDITED_STAGING",
        "tokenAuth": {
            "enabled": false,
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": true,
            "percentageCoverage": "AUTO"
        },
        "contentTargeting": {
            "enabled": false,
            "geoProtection": {
                "enabled": false,
                "mode": "DENY",
                "countries": [],
                "dmas": [],
                "regions": [],
                "overrideIps": [],
                "geoRedirectOnDenyEnabled": false
            },
            "ipAccess": {
                "enabled": false,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": false,
                "ips": []
            },
            "referer": {
                "enabled": false,
                "domains": [],
                "referrerRedirectEnabled": false
            },
            "denyAnonymousProxies": false,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": false,
            "supportPlayerEnabled": false,
            "resetSupportPlayer": false,
            "players": []
        }
    },
    {
        "policyName": "Policy - Media Encryption",
        "policyId": 3,
        "description": "Test - Media Encryption",
        "environment": "staging",
        "status": "ACTIVE",
        "tokenAuth": {
            "enabled": false,
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": true,
            "percentageCoverage": "60"
        },
        "contentTargeting": {
            "enabled": false,
            "geoProtection": {
                "enabled": false,
                "mode": "DENY",
                "countries": [],
                "dmas": [],
                "regions": [],
                "overrideIps": [],
                "geoRedirectOnDenyEnabled": false
            },
            "ipAccess": {
                "enabled": false,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": false,
                "ips": []
            },
            "referer": {
                "enabled": false,
                "domains": [],
                "referrerRedirectEnabled": false
            },
            "denyAnonymousProxies": false,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": false,
            "supportPlayerEnabled": false,
            "resetSupportPlayer": false,
            "players": []
        }
    },
    {
        "policyName": "Policy - Player Verification",
        "policyId": 4,
        "description": "Test - Player Verification",
        "environment": "production",
        "status": "ACTIVE_DELETED_STAGING",
        "tokenAuth": {
            "enabled": false,
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": false,
            "percentageCoverage": "100"
        },
        "contentTargeting": {
            "enabled": false,
            "geoProtection": {
                "enabled": false,
                "mode": "DENY",
                "countries": [],
                "dmas": [],
                "regions": [],
                "overrideIps": [],
                "geoRedirectOnDenyEnabled": false
            },
            "ipAccess": {
                "enabled": false,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": false,
                "ips": []
            },
            "referer": {
                "enabled": false,
                "domains": [],
                "referrerRedirectEnabled": false
            },
            "denyAnonymousProxies": false,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": true,
            "supportPlayerEnabled": true,
            "resetSupportPlayer": false,
            "players": [
                {
                    "hash": "SAMPLEHASH",
                    "description": "Sample Player",
                    "enabled": true
                }
            ],
            "ttl": "1d",
            "email": "tst-demo@akamai.com"
        }
    },
    {
        "policyName": "Policy - Player Verification",
        "policyId": 4,
        "description": "Test - Player Verification",
        "environment": "staging",
        "status": "DELETED",
        "tokenAuth": {
            "enabled": false,
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": false,
            "percentageCoverage": "100"
        },
        "contentTargeting": {
            "enabled": false,
            "geoProtection": {
                "enabled": false,
                "mode": "DENY",
                "countries": [],
                "dmas": [],
                "regions": [],
                "overrideIps": [],
                "geoRedirectOnDenyEnabled": false
            },
            "ipAccess": {
                "enabled": false,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": false,
                "ips": []
            },
            "referer": {
                "enabled": false,
                "domains": [],
                "referrerRedirectEnabled": false
            },
            "denyAnonymousProxies": false,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": true,
            "supportPlayerEnabled": true,
            "resetSupportPlayer": false,
            "players": [
                {
                    "hash": "SAMPLEHASH",
                    "description": "Sample Player",
                    "enabled": true
                }
            ],
            "ttl": "1d",
            "email": "tst-demo@akamai.com"
        }
    },
    {
        "policyName": "Policy - Token Auth",
        "policyId": 5,
        "description": "Test - Token Auth",
        "environment": "production",
        "status": "ACTIVE",
        "tokenAuth": {
            "enabled": true,
            "password": "c319f970fd89b9f8c3d48e25548c793d",
            "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": false,
            "percentageCoverage": "100"
        },
        "contentTargeting": {
            "enabled": false,
            "geoProtection": {
                "enabled": false,
                "mode": "DENY",
                "countries": [],
                "dmas": [],
                "regions": [],
                "overrideIps": [],
                "geoRedirectOnDenyEnabled": false
            },
            "ipAccess": {
                "enabled": false,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": false,
                "ips": []
            },
            "referer": {
                "enabled": false,
                "domains": [],
                "referrerRedirectEnabled": false
            },
            "denyAnonymousProxies": false,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": false,
            "supportPlayerEnabled": false,
            "resetSupportPlayer": false,
            "players": []
        }
    },
    {
        "policyName": "Policy - Token Auth",
        "policyId": 5,
        "description": "Test - Token Auth",
        "environment": "staging",
        "status": "ACTIVE",
        "tokenAuth": {
            "enabled": true,
            "password": "c319f970fd89b9f8c3d48e25548c793d",
            "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": false,
            "percentageCoverage": "100"
        },
        "contentTargeting": {
            "enabled": false,
            "geoProtection": {
                "enabled": false,
                "mode": "DENY",
                "countries": [],
                "dmas": [],
                "regions": [],
                "overrideIps": [],
                "geoRedirectOnDenyEnabled": false
            },
            "ipAccess": {
                "enabled": false,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": false,
                "ips": []
            },
            "referer": {
                "enabled": false,
                "domains": [],
                "referrerRedirectEnabled": false
            },
            "denyAnonymousProxies": false,
            "denyTransparentProxies": false
        },
        "playerVerification": {
            "enabled": false,
            "supportPlayerEnabled": false,
            "resetSupportPlayer": false,
            "players": []
        }
    }
]

Create a policy

When creating a security policy, it is placed into a staging environment. You must Patch a policy to production before it can be assigned to a configuration.

POST /config-media-security/v2/policies

Content-Type: application/json

Object type: Policy

Download schema: PolicyPostDTO.json

Request Body:

{
    "policyName": "Policy - All Features",
    "description": "Test demo policy",
    "contractId": "CTR-123",
    "groupId": "123",
    "promote": false,
    "tokenAuth": {
        "enabled": true,
        "password": "c319f970fd89b9f8c3d48e25548c793d",
        "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
        "enforceOnInitialRequest": true,
        "enforceOnContentRequest": true
    },
    "mediaEncryption": {
        "enabled": true,
        "percentageCoverage": "AUTO"
    },
    "contentTargeting": {
        "enabled": true,
        "geoProtection": {
            "enabled": true,
            "mode": "ALLOW",
            "countries": [
                {
                    "countryCode": "IN"
                }
            ],
            "dmas": [
                {
                    "dmaCode": "501"
                }
            ],
            "regions": [
                {
                    "regionCode": "CA",
                    "countryCode": "US"
                }
            ],
            "overrideIps": [
                "55.55.55.100",
                "55.55.55.101"
            ],
            "geoRedirectOnDenyEnabled": true,
            "geoRedirectOnDenyURL": "https://www.akamai.com"
        },
        "ipAccess": {
            "enabled": true,
            "mode": "DENY",
            "ipRedirectOnDenyEnabled": true,
            "denyOnIPRedirectURL": "https://www.akamai.com",
            "ips": [
                "55.55.55.102"
            ]
        },
        "referer": {
            "enabled": true,
            "domains": [
                "akamai.com"
            ],
            "referrerRedirectEnabled": true,
            "referrerRedirectURL": "https://www.akamai.com"
        },
        "denyAnonymousProxies": true,
        "denyTransparentProxies": false
    },
    "playerVerification": {
        "enabled": true,
        "supportPlayerEnabled": true,
        "email": "tst-demo@akamai.com",
        "resetSupportPlayer": false,
        "players": [
            {
                "description": "Sample Player",
                "hash": "SAMPLEHASH",
                "enabled": true
            }
        ],
        "ttl": "1d"
    }
}

Status 201 application/json

Download schema: PolicyActionResponseDTO.json

Response Body:

{
    "message": "Successfully created security policy:1"
}

Status 202 application/json

Download schema: PolicyActionResponseDTO.json

Response Body:

{
    "message": "Successfully created and promoted security policy:1"
}

Create a Security Policy

Create a new policy based on your requirements. In this example, the policy enables Token Authorization and various Content Targeting protections. Player Verification is enabled by including a hash of an applicable player.

Member/type pairs: The pairs used in the POST Body content are described in the sections that follow.

  1. Policy members
  2. Designated Market Area members
  3. Player Verfication

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

Response example: Upon successful creation of a new policy, the response includes 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.

Get a policy

Get details of security policy settings.

GET /config-media-security/v2/policies/{policyId}

Sample: /config-media-security/v2/policies/1

Parameter Type Sample Description
URL parameters
policyId Integer 1 Unique identifier for each policy.

Status 200 application/json

Object type: Policy

Download schema: PolicyDTO.json

Response Body:

{
    "policyName": "Policy - All Features",
    "policyId": "1",
    "description": "Test demo policy",
    "status": "EDITED",
    "tokenAuth": {
        "enabled": true,
        "password": "c319f970fd89b9f8c3d48e25548c793d",
        "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
        "enforceOnInitialRequest": true,
        "enforceOnContentRequest": true
    },
    "mediaEncryption": {
        "enabled": true,
        "percentageCoverage": "AUTO"
    },
    "contentTargeting": {
        "enabled": true,
        "geoProtection": {
            "enabled": true,
            "mode": "ALLOW",
            "countries": [
                {
                    "countryCode": "IN"
                }
            ],
            "dmas": [
                {
                    "dmaCode": "501"
                }
            ],
            "regions": [
                {
                    "countryCode": "US",
                    "regionCode": "CA"
                }
            ],
            "overrideIps": [
                "55.55.55.100",
                "55.55.55.101"
            ],
            "geoRedirectOnDenyEnabled": true,
            "geoRedirectOnDenyURL": "https://www.akamai.com"
        },
        "ipAccess": {
            "enabled": true,
            "mode": "DENY",
            "ipRedirectOnDenyEnabled": true,
            "denyOnIPRedirectURL": "https://www.akamai.com",
            "ips": [
                "55.55.55.102"
            ]
        },
        "referer": {
            "enabled": true,
            "domains": [
                "akamai.com"
            ],
            "referrerRedirectEnabled": true,
            "referrerRedirectURL": "https://www.akamai.com"
        },
        "denyAnonymousProxies": true,
        "denyTransparentProxies": false
    },
    "playerVerification": {
        "enabled": true,
        "supportPlayerEnabled": true,
        "resetSupportPlayer": false,
        "players": [
            {
                "hash": "SAMPLEHASH",
                "description": "Sample Player",
                "enabled": true
            }
        ],
        "ttl": "1d",
        "email": "tst-demo@akamai.com"
    },
    "unsavedPolicy": {
        "policyName": "Policy - All Features",
        "description": "Test demo policy",
        "tokenAuth": {
            "enabled": true,
            "password": "478bdf12ee2e785b1c64ed818c643934",
            "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": true,
            "percentageCoverage": "30"
        },
        "playerVerification": {
            "enabled": true,
            "supportPlayerEnabled": true,
            "resetSupportPlayer": false,
            "players": [
                {
                    "hash": "SAMPLEHASH2",
                    "description": "Sample Player2",
                    "enabled": true
                },
                {
                    "hash": "SAMPLEHASH",
                    "description": "Sample Player1",
                    "enabled": true
                }
            ],
            "ttl": "1d",
            "email": "demo@akamai.com"
        },
        "contentTargeting": {
            "enabled": true,
            "geoProtection": {
                "enabled": true,
                "mode": "DENY",
                "countries": [
                    {
                        "countryCode": "IN"
                    }
                ],
                "dmas": [
                    {
                        "dmaCode": "501"
                    }
                ],
                "regions": [
                    {
                        "countryCode": "US",
                        "regionCode": "CA"
                    }
                ],
                "overrideIps": [
                    "55.55.55.100",
                    "55.55.55.101"
                ],
                "geoRedirectOnDenyEnabled": true,
                "geoRedirectOnDenyURL": "https://www.akamai.com"
            },
            "ipAccess": {
                "enabled": true,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": true,
                "denyOnIPRedirectURL": "https://www.akamai.com",
                "ips": [
                    "55.55.55.102"
                ]
            },
            "referer": {
                "enabled": true,
                "domains": [
                    "akamai.com"
                ],
                "referrerRedirectEnabled": true,
                "referrerRedirectURL": "https://www.akamai.com"
            },
            "denyAnonymousProxies": true,
            "denyTransparentProxies": false
        }
    }
}

Modify a policy

Updates security policy settings.

PUT /config-media-security/v2/policies/{policyId}

Sample: /config-media-security/v2/policies/1

Content-Type: application/json

Object type: Policy

Download schema: PolicyPutDTO.json

Request Body:

{
    "policyName": "Policy - All Features",
    "description": "Test demo policy",
    "promote": false,
    "tokenAuth": {
        "enabled": true,
        "password": "478bdf12ee2e785b1c64ed818c643934",
        "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
        "enforceOnInitialRequest": true,
        "enforceOnContentRequest": true
    },
    "mediaEncryption": {
        "enabled": true,
        "percentageCoverage": "30"
    },
    "contentTargeting": {
        "enabled": true,
        "geoProtection": {
            "enabled": true,
            "mode": "DENY",
            "countries": [
                {
                    "countryCode": "IN"
                }
            ],
            "dmas": [
                {
                    "dmaCode": "501"
                }
            ],
            "regions": [
                {
                    "countryCode": "US",
                    "regionCode": "CA"
                }
            ],
            "overrideIps": [
                "55.55.55.100",
                "55.55.55.101"
            ],
            "geoRedirectOnDenyEnabled": true,
            "geoRedirectOnDenyURL": "https://www.akamai.com"
        },
        "ipAccess": {
            "enabled": true,
            "mode": "DENY",
            "ipRedirectOnDenyEnabled": true,
            "denyOnIPRedirectURL": "https://www.akamai.com",
            "ips": [
                "55.55.55.102"
            ]
        },
        "referer": {
            "enabled": true,
            "domains": [
                "akamai.com"
            ],
            "referrerRedirectEnabled": true,
            "referrerRedirectURL": "https://www.akamai.com"
        },
        "denyAnonymousProxies": true,
        "denyTransparentProxies": false
    },
    "playerVerification": {
        "enabled": true,
        "supportPlayerEnabled": true,
        "resetSupportPlayer": false,
        "players": [
            {
                "hash": "SAMPLEHASH",
                "description": "Sample Player1",
                "enabled": true
            },
            {
                "hash": "SAMPLEHASH2",
                "description": "Sample Player2",
                "enabled": true
            }
        ],
        "ttl": "1d",
        "email": "demo@akamai.com"
    }
}
Parameter Type Sample Description
URL parameters
policyId Integer 1 Unique identifier for each policy.

Status 201 application/json

Download schema: PolicyActionResponseDTO.json

Response Body:

{
    "message": "Successfully edited security policy:1"
}

Status 202 application/json

Download schema: PolicyActionResponseDTO.json

Response Body:

{
    "message": "Successfully edited and promoted security policy:1"
}

Modify a Policy

  1. Run the Get a Policy operation to obtain your existing policy.

  2. Modify the Policies object using PUT data as a reference.

  3. PUT the object to /config-media-security/v2/policies/{policyId}.

Delete a policy

A policy must first be set as markForDelete from the staging environment before issuing delete. The policy will be removed from the list immediately after issuing a delete.

DELETE /config-media-security/v2/policies/{policyId}

Sample: /config-media-security/v2/policies/1

Parameter Type Sample Description
URL parameters
policyId Integer 1 Unique identifier for each policy.

Status 200 application/json

Download schema: PolicyActionResponseDTO.json

Response Body:

{
    "message": "Successfully deleted Security policy:1"
}

Patch a policy

Promote a policy to production, restore a policy, or mark a policy for deletion on the staging network.

PATCH /config-media-security/v2/policies/{policyId}

Sample: /config-media-security/v2/policies/1

Content-Type: application/json

Object type: Patch

Download schema: PolicyPatchDTO.json

Request Body:

{
    "promote": true,
    "reset": false,
    "markForDelete": false
}
Parameter Type Sample Description
URL parameters
policyId Integer 1 Unique identifier for each policy.

Status 200 application/json

Download schema: PolicyActionResponseDTO.json

Response Body:

{
    "message": "Successfully promoted security policy:2"
}

Promote a Policy from Staging to Production

After creation, a policy is available 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.

  1. Obtain the policy of interest from the listed Policies
  2. PATCH the object to Promote a Policy /config-media-security/v2/policies/{policyId}.

List policy assignments

Get all assignments for the given policy.

GET /config-media-security/v2/policies/{policyId}/assignments

Sample: /config-media-security/v2/policies/1/assignments

Parameter Type Sample Description
URL parameters
policyId Integer 1 Unique identifier for each policy.

Status 200 application/json

Object type: AssignmentStatus

Download schema: PolicyAssignmentsDTO.json

Response Body:

{
    "status": "PROMOTED",
    "assignments": [
        {
            "configurationName": "demo-live-01",
            "configurationXmlName": "demo-lh.akamaihd.net.xml",
            "configurationType": "Media Services Live (Stream Packaging)",
            "policyId": 1,
            "policyName": "tst-policy-1",
            "pathCreatedTime": "2018-01-01T00:00:00",
            "path": "/tst",
            "startTime": "2018-01-05T11:00:00",
            "endTime": "*"
        },
        {
            "configurationName": "demo-vod",
            "configurationXmlName": "demo-vod.xml",
            "configurationType": "Media Services On Demand (Stream Packaging)",
            "policyId": 2,
            "policyName": "tst-policy-2",
            "pathCreatedTime": "2018-12-13T00:00:00",
            "path": "/...",
            "startTime": "*",
            "endTime": "*"
        }
    ]
}

List configurations

Get all configurations for the account.

GET /config-media-security/v2/configurations

Status 200 application/json

Object type: Configuration

Download schema: ConfigurationsDTO.json

Response Body:

[
    {
        "configurationId": 1234,
        "configurationName": "demo-live-01",
        "configurationXmlName": "demo-lh.akamaihd.net.xml",
        "hostname": "demo-lh.akamaihd.net",
        "configurationType": "Media Services Live (Stream Packaging)",
        "digitalProperties": {
            "production": [
                "demo-lh.akamaihd.net",
                "*-demo-lh.akamaihd.net"
            ],
            "staging": [
                "*-demo-lh.akamaihd-staging.net",
                "demo-lh.akamaihd-staging.net",
                "demo-lh.akamaihd.net",
                "*-demo-lh.akamaihd.net"
            ]
        },
        "isActiveInProduction": true
    },
    {
        "configurationId": 12345,
        "configurationName": "demo-vod",
        "configurationXmlName": "demo-vod.xml",
        "hostname": "demo-vh.akamaihd.net",
        "configurationType": "Media Services On Demand (Stream Packaging)",
        "digitalProperties": {
            "production": [
                "demo-vh.akamaihd.net"
            ],
            "staging": [
                "demo-vh.akamaihd.net"
            ]
        },
        "isActiveInProduction": true
    }
]

List policy assignments per configuration

Get all policy assignments for the given configuration.

GET /config-media-security/v2/configurations/{domain}/assignments

Sample: /config-media-security/v2/configurations/speedy.example.com/assignments

Parameter Type Sample Description
URL parameters
domain String speedy.example.com The digital property that represents the Configuration.

Status 200 application/json

Object type: AssignmentStatus

Download schema: PolicyAssignmentsForConfigurationDTO.json

Response Body:

{
    "status": "PROMOTED",
    "assignments": [
        {
            "configurationName": "demo-live-01",
            "configurationXmlName": "demo-lh.akamaihd.net.xml",
            "configurationType": "Media Services Live (Stream Packaging)",
            "policyId": 1,
            "policyName": "tst-policy-1",
            "pathCreatedTime": "2018-01-01T00:00:00",
            "path": "/tst",
            "startTime": "2018-01-05T11:00:00",
            "endTime": "*"
        },
        {
            "configurationName": "demo-vod",
            "configurationXmlName": "demo-vod.xml",
            "configurationType": "Media Services On Demand (Stream Packaging)",
            "policyId": 2,
            "policyName": "tst-policy-2",
            "pathCreatedTime": "2018-12-13T00:00:00",
            "path": "/...",
            "startTime": "*",
            "endTime": "*"
        }
    ]
}

Create or modify a policy assignment

Create/update policy assignments for the given configuration.

PUT /config-media-security/v2/configurations/{domain}/assignments

Sample: /config-media-security/v2/configurations/speedy.example.com/assignments

Content-Type: application/json

Object type: Assignments

Download schema: PolicyAssignmentPutDTO.json

Request Body:

{
    "assignments": [
        {
            "policyId": 1,
            "path": "/...",
            "startTime": "*",
            "endTime": "*"
        },
        {
            "policyId": 2,
            "path": "/tst",
            "startTime": "2018-01-01T11:00:00",
            "endTime": "*"
        }
    ]
}
Parameter Type Sample Description
URL parameters
domain String speedy.example.com The digital property that represents the Configuration.

Status 201

Headers:

Location: /configurations/{domain}/assignments

Status 202

Headers:

Location: /configurations/{domain}/assignments

Modify Policy Assignments of a Config

Multiple security policies can be used to create or modify assignments of a config policy. The domain variable in the initial call syntax is the digital property that represents the HD Configuration and can be obtained by performing a List Configurations call.

  1. GET the current configuration assignments.

  2. Modify the Assignments object for the domain in your HD Configuration.

  3. PUT the object to /config-media-security/v2/configurations/{domain}/assignments

Patch a policy assignment

Promote policy assignments to production network or restore the policy assignments on the staging network for the given configuration.

PATCH /config-media-security/v2/configurations/{domain}/assignments

Sample: /config-media-security/v2/configurations/speedy.example.com/assignments

Content-Type: application/json

Object type: Patch

Download schema: PolicyAssignmentPatchDTO.json

Request Body:

{
    "promote": true,
    "reset": false
}
Parameter Type Sample Description
URL parameters
domain String speedy.example.com The digital property that represents the Configuration.

Status 200 application/json

Object type: AssignmentStatus

Download schema: PolicyAssignmentsForConfigurationDTO.json

Response Body:

{
    "status": "PROMOTED",
    "assignments": [
        {
            "configurationName": "demo-live-01",
            "configurationXmlName": "demo-lh.akamaihd.net.xml",
            "configurationType": "Media Services Live (Stream Packaging)",
            "policyId": 1,
            "policyName": "tst-policy-1",
            "pathCreatedTime": "2018-01-01T00:00:00",
            "path": "/tst",
            "startTime": "2018-01-05T11:00:00",
            "endTime": "*"
        },
        {
            "configurationName": "demo-vod",
            "configurationXmlName": "demo-vod.xml",
            "configurationType": "Media Services On Demand (Stream Packaging)",
            "policyId": 2,
            "policyName": "tst-policy-2",
            "pathCreatedTime": "2018-12-13T00:00:00",
            "path": "/...",
            "startTime": "*",
            "endTime": "*"
        }
    ]
}

Assign a policy to an HD configuration

With a policy promoted to Production, it can now be assigned to an HD configuration of content. The domain variable in the initial call syntax is the digital property hostname that represents the HD configuration.

  1. List Configurations to obtain the hostname of interest. Use this as the domain when Patching a policy assignment.

  2. PATCH the object with the necessary Assignments members to Promote the Policy Assignment.

Data

This section provides you with the data model for the Media Security Policy API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.
Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored.

Region

Specifies a part of a country, such as a U.S. state or Canadian province, which you can use to target a policy’s location.

Download schema: RegionsDTO.json

Sample GET response:

[
    {
        "countryCode": "AU",
        "regionCode": "ACT",
        "regionName": "Australian Capital Territory"
    },
    {
        "countryCode": "AU",
        "regionCode": "NSW",
        "regionName": "New South Wales"
    },
    {
        "countryCode": "AU",
        "regionCode": "NT",
        "regionName": "Northern Territory"
    },
    {
        "countryCode": "AU",
        "regionCode": "QLD",
        "regionName": "Queensland"
    },
    {
        "countryCode": "AU",
        "regionCode": "SA",
        "regionName": "South Australia"
    },
    {
        "countryCode": "AU",
        "regionCode": "TAS",
        "regionName": "Tasmania"
    },
    {
        "countryCode": "US",
        "regionCode": "WV",
        "regionName": "West Virginia"
    },
    {
        "countryCode": "US",
        "regionCode": "WY",
        "regionName": "Wyoming"
    }
]

Region members

Member Type Required Description
Region: Specifies a part of a country, such as a U.S. state or Canadian province, which you can use to target a policy’s location.
countryCode String Specifies the Country Code.
regionCode String Specifies the Region Code.
regionName String Specifies the Region Name.

DesignatedMarketArea

Specifies the Designated Market Area (DMA) code (United States, only), such as 501, which you can use to target a policy’s location. A list of supported DMA codes is available in Control Center.

Download schema: DmasDTO.json

Sample GET response:

[
    {
        "dmaCode": "500",
        "dmaName": "Portland-Auburn::ME,NH"
    },
    {
        "dmaCode": "501",
        "dmaName": "NewYork::CT,NJ,NY,PA"
    },
    {
        "dmaCode": "502",
        "dmaName": "Binghamton::NY"
    },
    {
        "dmaCode": "503",
        "dmaName": "Macon::GA"
    },
    {
        "dmaCode": "504",
        "dmaName": "Philadelphia::DE,NJ,PA"
    },
    {
        "dmaCode": "505",
        "dmaName": "Detroit::MI"
    },
    {
        "dmaCode": "868",
        "dmaName": "Chico-Redding::CA"
    },
    {
        "dmaCode": "881",
        "dmaName": "Spokane::ID,MT,OR,WA"
    }
]

DesignatedMarketArea members

Member Type Required Description
DesignatedMarketArea: Specifies the Designated Market Area (DMA) code (United States, only), such as 501, which you can use to target a policy’s location. A list of supported DMA codes is available in Control Center.
dmaCode String The DMA code represented by a string-formatted integer.
dmaName String The DMA name represents both city name and the set of states covered by the area.

Country

Specifies a country using a two-digit country code, such as US or JP, which you can use to target a policy’s location. Continents and countries are one-to-many.

Download schema: CountriesDTO.json

Sample GET response:

[
    {
        "countryCode": "AD",
        "countryName": "Andorra",
        "continentCode": "EU"
    },
    {
        "countryCode": "AE",
        "countryName": "United Arab Emirates",
        "continentCode": "AS"
    },
    {
        "countryCode": "AF",
        "countryName": "Afghanistan",
        "continentCode": "AS"
    },
    {
        "countryCode": "AG",
        "countryName": "Antigua and Barbuda",
        "continentCode": "NA"
    },
    {
        "countryCode": "AI",
        "countryName": "Anguilla",
        "continentCode": "NA"
    },
    {
        "countryCode": "ZW",
        "countryName": "Zimbabwe",
        "continentCode": "AF"
    }
]

Country members

Member Type Required Description
Country: Specifies a country using a two-digit country code, such as US or JP, which you can use to target a policy’s location. Continents and countries are one-to-many.
continentCode String Specifies a two-letter continent. For example, NA for North America and EU for Europe. A list of supported continent codes is available in Control Center.
countryCode String Specifies a two-letter country. For example, US for United States and IN for India. A list of supported country codes is available in Control Center.
countryName String Specifies the country name.

Policy

A policy encompasses security services you define to protect your media content.

Download schema: PolicyDTO.json, PolicyPostDTO.json, PolicyPutDTO.json

Sample GET response for a policy actively in staging:

{
    "policyName": "Policy - All Features",
    "policyId": "1",
    "description": "Test demo policy",
    "status": "EDITED",
    "tokenAuth": {
        "enabled": true,
        "password": "c319f970fd89b9f8c3d48e25548c793d",
        "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
        "enforceOnInitialRequest": true,
        "enforceOnContentRequest": true
    },
    "mediaEncryption": {
        "enabled": true,
        "percentageCoverage": "AUTO"
    },
    "contentTargeting": {
        "enabled": true,
        "geoProtection": {
            "enabled": true,
            "mode": "ALLOW",
            "countries": [
                {
                    "countryCode": "IN"
                }
            ],
            "dmas": [
                {
                    "dmaCode": "501"
                }
            ],
            "regions": [
                {
                    "countryCode": "US",
                    "regionCode": "CA"
                }
            ],
            "overrideIps": [
                "55.55.55.100",
                "55.55.55.101"
            ],
            "geoRedirectOnDenyEnabled": true,
            "geoRedirectOnDenyURL": "https://www.akamai.com"
        },
        "ipAccess": {
            "enabled": true,
            "mode": "DENY",
            "ipRedirectOnDenyEnabled": true,
            "denyOnIPRedirectURL": "https://www.akamai.com",
            "ips": [
                "55.55.55.102"
            ]
        },
        "referer": {
            "enabled": true,
            "domains": [
                "akamai.com"
            ],
            "referrerRedirectEnabled": true,
            "referrerRedirectURL": "https://www.akamai.com"
        },
        "denyAnonymousProxies": true,
        "denyTransparentProxies": false
    },
    "playerVerification": {
        "enabled": true,
        "supportPlayerEnabled": true,
        "resetSupportPlayer": false,
        "players": [
            {
                "hash": "SAMPLEHASH",
                "description": "Sample Player",
                "enabled": true
            }
        ],
        "ttl": "1d",
        "email": "tst-demo@akamai.com"
    },
    "unsavedPolicy": {
        "policyName": "Policy - All Features",
        "description": "Test demo policy",
        "tokenAuth": {
            "enabled": true,
            "password": "478bdf12ee2e785b1c64ed818c643934",
            "transitionPassword": "c319f970fd89b9f8c3d48e25548c793d",
            "enforceOnInitialRequest": true,
            "enforceOnContentRequest": true
        },
        "mediaEncryption": {
            "enabled": true,
            "percentageCoverage": "30"
        },
        "playerVerification": {
            "enabled": true,
            "supportPlayerEnabled": true,
            "resetSupportPlayer": false,
            "players": [
                {
                    "hash": "SAMPLEHASH2",
                    "description": "Sample Player2",
                    "enabled": true
                },
                {
                    "hash": "SAMPLEHASH",
                    "description": "Sample Player1",
                    "enabled": true
                }
            ],
            "ttl": "1d",
            "email": "demo@akamai.com"
        },
        "contentTargeting": {
            "enabled": true,
            "geoProtection": {
                "enabled": true,
                "mode": "DENY",
                "countries": [
                    {
                        "countryCode": "IN"
                    }
                ],
                "dmas": [
                    {
                        "dmaCode": "501"
                    }
                ],
                "regions": [
                    {
                        "countryCode": "US",
                        "regionCode": "CA"
                    }
                ],
                "overrideIps": [
                    "55.55.55.100",
                    "55.55.55.101"
                ],
                "geoRedirectOnDenyEnabled": true,
                "geoRedirectOnDenyURL": "https://www.akamai.com"
            },
            "ipAccess": {
                "enabled": true,
                "mode": "DENY",
                "ipRedirectOnDenyEnabled": true,
                "denyOnIPRedirectURL": "https://www.akamai.com",
                "ips": [
                    "55.55.55.102"
                ]
            },
            "referer": {
                "enabled": true,
                "domains": [
                    "akamai.com"
                ],
                "referrerRedirectEnabled": true,
                "referrerRedirectURL": "https://www.akamai.com"
            },
            "denyAnonymousProxies": true,
            "denyTransparentProxies": false
        }
    }
}

Policy members

Member Type GET POST PUT Description
Policy: A policy encompasses security services you define to protect your media content.
contentTargeting ContentTargeting Allow or deny access to your content based on proxies, geographic location, specific IP, and referrer websites.
contractId String Specifies the contract applicable to your specific Media Security Policy instance. Contract will be chosen automatically if not provided.
description String A description you provide to help you manage your policies.
environment Array Read-only. Defines the environments. Values are PRODUCTION or STAGING.
groupId String Specifies the group applicable to your specific Media Security Policy instance.
mediaEncryption MediaEncryption Define encryption settings for your HDS-format media content. Enabling media encryption will automatically incorporate AES–128 encryption for HLS-format content.
playerVerification PlayerVerification Settings to define approved media players. This ensures only authorized clients receive content.
policyId Integer Read-only. Unique ID number for the policy.
policyName String Unique name for the policy.
promote Boolean Determines if the policy must be created and promoted to production. If this is not provided or set to false, policy will be created only in staging network.
status String Read-only. Defines the status of the policy.
tokenAuth TokenAuthorization Defines the token authorization settings to ensure only authenticated users gain access to media streams.
unsavedPolicy Policy Defines the staging version of the policy. You can review any changes made to the policy.

Patch

Promote a policy to production, restore a policy, or mark a policy for deletion on the staging network.

Download schema: PolicyPatchDTO.json

Patch members

Member Type Required Description
Patch: Promote a policy to production, restore a policy, or mark a policy for deletion on the staging network.
markForDelete Boolean Determines if the policy should be marked for deletion. This must be set to true before the delete option can be used.
promote Boolean Determines if the policy should be promoted to production network.
reset Boolean Determines if the policy should be restored on the staging network.

TokenAuthorization

Defines the token authorization settings to ensure only authenticated users gain access to media streams. These settings apply to the entire policy, and are unique per-policy.

Download schema: TokenAuthDTO.json

TokenAuthorization members

Member Type Required Description
TokenAuthorization: Defines the token authorization settings to ensure only authenticated users gain access to media streams. These settings apply to the entire policy, and are unique per-policy.
enabled Boolean Determines if token authorization is enabled. A password must be set when enabling this feature.
enforceOnContentRequest Boolean Protect segmented content playback by performing cookie-based token verification.
enforceOnInitialRequest Boolean Enforce token verification on initial request. This provides a ‘Time to Live’ (TTL) value for the URL.
password String The primary password established for this protection. This member is required if enabled is true. The value must be in hexadecimal format, consist of an even number of characters, and be between 2 and 32 characters.
transitionPassword String This is an optional value, set to serve as a backup encryption key. When changing your primary password, the backup password serves in its place during any latency that may occur. The value must be in hexadecimal format, consist of an even number of characters, and be between 2 and 32 characters.

MediaEncryption

Define encryption settings for your HDS-format media content. Enabling media encryption will automatically incorporate full AES–128 encryption for HLS-format content. These settings apply to the entire policy, and are unique per-policy.

Download schema: MediaEncryptionDTO.json

MediaEncryption members

Member Type Required Description
MediaEncryption: Define encryption settings for your HDS-format media content. Enabling media encryption will automatically incorporate full AES–128 encryption for HLS-format content. These settings apply to the entire policy, and are unique per-policy.
enabled Boolean Specifies if percentage coverage settings will be applied.
percentageCoverage String Valid encryption settings include a string-formatted integer percentage between 1-100, ALL, or use AUTO to allow Media Security Policy to determine the appropriate level. Partial encryption coverage begins from the beginning of content to block unwanted users from accessing the full media. Less encryption requires less work on the part of the player. AUTO will apply the percentage value based on the associated Media Services Configuration.

ContentTargeting

Allow or deny access to your content based on proxies, geographic location, specific IP, and referrer websites. These settings apply to the entire policy, and are unique per-policy.

Download schema: ContentTargetingDTO.json

ContentTargeting members

Member Type Required Description
ContentTargeting: Allow or deny access to your content based on proxies, geographic location, specific IP, and referrer websites. These settings apply to the entire policy, and are unique per-policy.
denyAnonymousProxies Boolean When true, denies requests by known anonymous proxies, which are used to hide information about a requesting client.
denyTransparentProxies Boolean When true, denies requests by transparent proxies that intercept and eliminate client side configurations.
enabled Boolean This setting must be true for content targeting protection settings to become active.
geoProtection ContentTargeting.geoProtection Allow or deny access based on region, and redirect denied access to an alternate URL.
ipAccess ContentTargeting.ipAccess Available policies based on IP address.
referer ContentTargeting.referer Configuration policies based on the request’s Referrer HTTP header.
ContentTargeting.geoProtection: Allow or deny access based on region, and redirect denied access to an alternate URL.
countries Country array Countries to assign geo protection to, a set of objects available from the List countries operation.
dmas Designated Market Area array Defines the list of DMA’s enabled for geo protection. A list of supported DMA codes is available in Control Center.
enabled Boolean Determines if geo protection functionality is enabled within content targeting.
geoRedirectOnDenyEnabled Boolean When true, denied attempts will redirect to the configured geoRedirectOnDenyURL.
geoRedirectOnDenyURL String Defines the redirection URL for denied requests. This applies only if geoRedirectOnDenyEnabled is true.
mode Enumeration Specifies whether to ALLOW or DENY requests from the set of locations you define.
overrideIps Array Defines a set of ip addresses or cidr blocks to always allow access, regardless of location. 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.
regions Region array Regions to assign geo protection to, a set of objects available from the List regions operation.
ContentTargeting.ipAccess: Available policies based on IP address.
denyOnIPRedirectURL String Defines the redirection URL for denied requests. This applies only if ipRedirectOnDenyEnabled is true.
enabled Boolean This setting must be true for ip access list settings to become active.
ipRedirectOnDenyEnabled Boolean When true, denied attempts will redirect to the configured denyOnIPRedirectURL.
ips Array Defines specific ip addresses or cidr blocks that are to be allowed or blocked access (i.e., based on what was set for mode).
mode Enumeration Defines if ip addresses/cidr blocks specified should be allowed or blocked from accessing content. Allowed values are ALLOW and DENY.
ContentTargeting.referer: Configuration policies based on the request’s Referrer HTTP header.
domains Array List specific domain URLs that are to be allowed access as a referrer.
enabled Boolean This setting must be true for referrer checking protection settings to become active.
referrerRedirectEnabled Boolean When true, denied attempts will redirect to the configured referrerRedirectURL.
referrerRedirectURL String Defines redirect URL if request is denied. This is applicable only if referrerRedirectEnabled is true.

PlayerVerification

Settings to define approved media players. This ensures only authorized clients receive content. Media Security Policy enforces a 30 player per Security Policy limit.

Download schema: PlayerVerificationDTO.json

PlayerVerification members

Member Type Required Description
PlayerVerification: Settings to define approved media players. This ensures only authorized clients receive content. Media Security Policy enforces a 30 player per Security Policy limit.
email String When the supportPlayerEnabled member is set to true, the email member is required to receive an alert when the 24-hour validity period expires.
enabled Boolean Determines if player verification features are enabled and enforced.
players PlayerVerification.players[] Define specific players for inclusion, via SHA256 hash equivalent, that are to be allowed access.
resetSupportPlayer Boolean When enabled, this resets the Akamai test player for another 24 hours.
supportPlayerEnabled Boolean When set to true, an Akamai test player is set for testing the player verification security. The test player is valid in staging or production environments for a period of 24 hours from the time of policy creation. When enabled, the email member is required.
ttl String Defines a time to live for the player, formatted as a duration string with an integer, followed by d, h, m, s. In this example, 1d is used to expire the players after 1 day. Once expired, the specified players are invalidated. The ttl duration starts once you assign the policy to a configuration.
PlayerVerification.players[]: Define specific players for inclusion, via SHA256 hash equivalent, that are to be allowed access.
description String Description of the player.
enabled Boolean Player is usable when set to true.
hash String SHA–256 hash value of the uncompressed HLS (.swf, .swc) binary player file.

Assignments

Promote or configure policy assignments.

Download schema: PolicyAssignmentPutDTO.json

Sample GET response:

{
    "status": "PROMOTED",
    "assignments": [
        {
            "configurationName": "demo-live-01",
            "configurationXmlName": "demo-lh.akamaihd.net.xml",
            "configurationType": "Media Services Live (Stream Packaging)",
            "policyId": 1,
            "policyName": "tst-policy-1",
            "pathCreatedTime": "2018-01-01T00:00:00",
            "path": "/tst",
            "startTime": "2018-01-05T11:00:00",
            "endTime": "*"
        },
        {
            "configurationName": "demo-vod",
            "configurationXmlName": "demo-vod.xml",
            "configurationType": "Media Services On Demand (Stream Packaging)",
            "policyId": 2,
            "policyName": "tst-policy-2",
            "pathCreatedTime": "2018-12-13T00:00:00",
            "path": "/...",
            "startTime": "*",
            "endTime": "*"
        }
    ]
}

Assignments members

Member Type Required Description
Assignments: Promote or configure policy assignments.
assignments Assignments.assignments[] An assignment is the association between a security policy and a configuration. You can have multiple security policies assigned to a configuration.
promote Boolean Indicates if the policy assignments should be promoted to production network.
Assignments.assignments[]: An assignment is the association between a security policy and a configuration. You can have multiple security policies assigned to a configuration.
configurationName String Specifies the name for the configuration (typically the name of an configuration file, minus the .xml extension).
configurationType String Specifies the name of the product to assigned to the configuration. Products such as Media Services Live (Stream Packaging) or Media Services Live (Stream Packaging).
configurationXmlName String Specifies the .xml filename for the configuration.
endTime String ISO 8601 timestamp used to configure an end point of validity for the assignment.
path String Specifies the server path to the set of content within the configuration that the policy protects.
pathCreatedTime String ISO 8601 timestamp used to specify the time the path was last modified or created.
policyId Integer The unique Policy ID value associated with the policy to be applied to the configuration.
policyName String Specifies the name for the policy.
startTime String ISO 8601 timestamps used to configure a starting date/time of validity for the policy assignment. Additionally, this can be left open to apply no start time by setting an asterisk (*) as its value.

AssignmentStatus

List the status, assignments and pending assignments of the policy.

Download schema: PolicyAssignmentsDTO.json

AssignmentStatus members

Member Type Required Description
AssignmentStatus: List the status, assignments and pending assignments of the policy.
assignments Assignment array List of assignments in production for the given policy.
pendingAssignments Assignment array List of assignments by configurations which are pending to be pushed to Production for the given policy. This is not applicable if all the assignments for the policy is pushed to production.
status Enumeration Defines the status of policy assignments. Valid values are PROMOTED and PENDING_PRODUCTION.

Configuration

Available Configurations to assign Media Security Policies.

Download schema: ConfigurationsDTO.json

Sample GET response:

[
    {
        "configurationId": 1234,
        "configurationName": "demo-live-01",
        "configurationXmlName": "demo-lh.akamaihd.net.xml",
        "hostname": "demo-lh.akamaihd.net",
        "configurationType": "Media Services Live (Stream Packaging)",
        "digitalProperties": {
            "production": [
                "demo-lh.akamaihd.net",
                "*-demo-lh.akamaihd.net"
            ],
            "staging": [
                "*-demo-lh.akamaihd-staging.net",
                "demo-lh.akamaihd-staging.net",
                "demo-lh.akamaihd.net",
                "*-demo-lh.akamaihd.net"
            ]
        },
        "isActiveInProduction": true
    },
    {
        "configurationId": 12345,
        "configurationName": "demo-vod",
        "configurationXmlName": "demo-vod.xml",
        "hostname": "demo-vh.akamaihd.net",
        "configurationType": "Media Services On Demand (Stream Packaging)",
        "digitalProperties": {
            "production": [
                "demo-vh.akamaihd.net"
            ],
            "staging": [
                "demo-vh.akamaihd.net"
            ]
        },
        "isActiveInProduction": true
    }
]

Configuration members

Member Type Required Description
Configuration: Available Configurations to assign Media Security Policies.
configurationId Integer Reflects the ID for the configuration.
configurationName String Indicates the name for the configuration (typically the name of an configuration file, minus the .xml extension).
configurationType String Indicates the name of the product to assigned to the configuration. Products such as Media Services Live (Stream Packaging) or Media Services Live (Stream Packaging).
configurationXmlName String Reflects the .xml filename for the configuration.
digitalProperties Configuration.digitalProperties Object contains different sets of arrays for each network, each with a set of property names.
hostname String Reflects the digital property (hostname) that represents the configuration.
isActiveInProduction Boolean Indicates if the configuration is active in production or not.
Configuration.digitalProperties: Object contains different sets of arrays for each network, each with a set of property names.
{network} Array Object contains different sets of arrays for each network, each with a set of property names associated with the configuration.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

The Media Security Policy API responds with HTTP problem error objects that provide details useful for debugging.

The status member offers the applicable HTTP error code, the various detail members contain a basic description of the issue, and the instance member offers a unique ID value that may be used in troubleshooting the issue with technical support.

HTTP status codes

The following lists the range of HTTP response codes the API may produce for both success and error cases:

Code Description
200 The operation was successful.
201 Resource created.
202 Resource successfully accepted.
400 Badly formatted JSON. Compare with the schema.

Last modified: 3/13/2019