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:

Download this API’s RAML and JSON schema descriptors.

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, and set the access level to READ-WRITE.

This workflow can be summed up in four basic phases:

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.
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.
Assign the Policy to a Desired HD Configuration. Once your policy is in the production network, you can Modify a Policy Assignment per Config.
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.

Policy members
Designated Market Area members
Player Verification

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

Run the Get a Policy operation to obtain your existing policy.
Modify the Policies object using PUT data as a reference.
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.

Obtain the policy of interest from the listed Policies
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.

GET the current configuration assignments.
Modify the Assignments object for the domain in your HD Configuration.
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.

List Configurations to obtain the hostname of interest. Use this as the domain when Patching a policy assignment.
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.