
- Overview
- Resources
- API summary
- List regions
- List Designated Market Areas
- List countries
- List policies
- Create a policy
- Get a policy
- Modify a policy
- Delete a policy
- Patch a policy
- List policy assignments
- List configurations
- List policy assignments per configuration
- Create or modify a policy assignment
- Patch a policy assignment
- Data
- Errors
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 thepolicyId
when promoting or modifying the policy. You can also List Policies to retrieve thepolicyId
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/ |
List Designated Market Areas | GET | /config-media-security/ |
List countries | GET | /config-media-security/ |
List policies | GET | /config-media-security/ |
Create a policy | POST | /config-media-security/ |
Get a policy | GET | /config-media-security/ |
Modify a policy | PUT | /config-media-security/ |
Delete a policy | DELETE | /config-media-security/ |
Patch a policy | PATCH | /config-media-security/ |
List policy assignments | GET | /config-media-security/ |
List configurations | GET | /config-media-security/ |
List policy assignments per configuration | GET | /config-media-security/ |
Create or modify a policy assignment | PUT | /config-media-security/ |
Patch a policy assignment | PATCH | /config-media-security/ |
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/
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/
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/
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/
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/
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 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.
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/
Sample: /config-media-security/
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/
Sample: /config-media-security/
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"
}
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/
Sample: /config-media-security/
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/
Sample: /config-media-security/
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/
Sample: /config-media-security/
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/
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/
Sample: /config-media-security/
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/
Sample: /config-media-security/
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/
Sample: /config-media-security/
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 thedomain
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 |
Content |
○ | ○ | ○ | 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 |
Media |
○ | ○ | ○ | Define encryption settings for your HDS-format media content. Enabling media encryption will automatically incorporate AES–128 encryption for HLS-format content. |
player |
Player |
○ | ○ | ○ | 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 |
Token |
○ | ○ | ○ | 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. |
enforce |
Boolean | ○ | Protect segmented content playback by performing cookie-based token verification. |
enforce |
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. |
transition |
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. |
percentage |
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. |
|||
deny |
Boolean | ○ | When true , denies requests by known anonymous proxies, which are used to hide information about a requesting client. |
deny |
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 |
Content |
○ | Allow or deny access based on region, and redirect denied access to an alternate URL. |
ipAccess |
Content |
○ | Available policies based on IP address. |
referer |
Content |
○ | 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. |
geo |
Boolean | ○ | When true , denied attempts will redirect to the configured geoRedirectOnDenyURL . |
geo |
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. |
|||
deny |
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. |
ip |
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. |
referrer |
Boolean | ○ | When true , denied attempts will redirect to the configured referrerRedirectURL . |
referrer |
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 |
Player |
✓ | Define specific players for inclusion, via SHA256 hash equivalent, that are to be allowed access. |
reset |
Boolean | ○ | When enabled, this resets the Akamai test player for another 24 hours. |
support |
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. |
○ | 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. |
|||
configuration |
String | ○ | Specifies the name for the configuration (typically the name of an configuration file, minus the .xml extension). |
configuration |
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) . |
configuration |
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. |
pending |
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. |
configuration |
String | ○ | Indicates the name for the configuration (typically the name of an configuration file, minus the .xml extension). |
configuration |
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) . |
configuration |
String | ○ | Reflects the .xml filename for the configuration. |
digital |
Configuration. |
○ | 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. |
is |
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. |