Use the /sapi/contentprotectionpolicy endpoint to manage content protection policies. A content protection policy defines a set of rules that restrict access to video content based on country, domain, IP address, or shared-secret token. Policies can be assigned to individual mediaclips or set as the default policy for an entire publication.
Base URL: https://yourcompanyname.bbvms.com/sapi/contentprotectionpolicy
All requests must be authenticated. See SAPI Authentication for details. All request bodies must use Content-Type: application/json.
1.0 | ContentProtectionPolicy Object
1.1 | Example ContentProtectionPolicy Object
{
"type": "ContentProtectionPolicy",
"id": "42",
"name": "NL and BE only",
"description": "Restrict playback to Netherlands and Belgium",
"status": "active",
"hideContent": false,
"labelPlacement": "center",
"backgroundColor": "#000000",
"textColor": "#ffffff",
"iconName": "lock-keyhole",
"rulesets": [
{
"filters": [
{
"id": "id000123",
"field": "country",
"operator": "containsAnyOf",
"value": ["Netherlands", "Belgium"]
}
]
}
],
"publicationid": "754",
"createddate": "2024-01-15T10:00:00Z",
"updateddate": "2024-03-20T09:30:00Z"
}1.2 | ContentProtectionPolicy Attributes
| Parameter | Description |
|---|---|
type | (string) Type of object: "ContentProtectionPolicy". Read-only. |
id | (string) Unique identifier of the policy. Read-only. |
name | (string) Human-readable policy name. |
description | (string) Optional description of the policy’s purpose. |
status | (string) "active" or "inactive". Only active policies are enforced during playback. |
hideContent | (boolean) When true, the video thumbnail and metadata are hidden for viewers who fail the policy check. When false, the content is visible but playback is blocked. |
rulesets | (array) One or more ruleset objects. A viewer must satisfy all filters within a ruleset to be allowed. When multiple rulesets are defined, a viewer must satisfy at least one ruleset in full. |
labelPlacement | (string) Position of the access-denied overlay: "center", "bottomRight", or "both". |
backgroundColor | (string) Hex colour code for the access-denied overlay background (e.g. "#000000"). |
textColor | (string) Optional hex colour code for the overlay text. |
iconName | (string) Optional icon name shown in the overlay (e.g. "lock-keyhole"). |
iconImg | (string) Optional URL to a custom icon image shown in the overlay. |
customLabel | (string) Optional custom text shown in the access-denied overlay. |
useCustomStyling | (boolean) When true, the textColor, iconName, iconImg, and customLabel values are applied to the overlay. |
publicationid | (string) Unique identifier of the publication. Read-only. |
createddate | (string) ISO 8601 date/time the policy was created. Read-only. |
updateddate | (string) ISO 8601 date/time the policy was last updated. Read-only. |
2.0 | Ruleset Structure
A policy contains one or more rulesets. Each ruleset contains one or more filters. The evaluation logic is:
- Filters within a ruleset are evaluated with AND: a viewer must match every filter in the ruleset.
- Multiple rulesets are evaluated with OR: a viewer who satisfies any one ruleset in full is granted access.
2.1 | Filter Attributes
| Parameter | Description |
|---|---|
id | (string) Unique identifier of the filter within the ruleset. |
field | (string) The attribute being evaluated. Accepted values: "country", "domain", "ip", "token". |
operator | (string) The comparison operator. See section 2.2. |
value | (string or array) The value(s) to compare against. |
2.2 | Supported Operators
| Operator | Description |
|---|---|
"is" | The field value exactly matches the specified value. |
"isNot" | The field value does not match the specified value. |
"containsAnyOf" | The field value matches at least one value in the specified array. |
"doesNotContainAnyOf" | The field value does not match any value in the specified array. |
"contains" | The field value contains the specified string. |
"doesNotContain" | The field value does not contain the specified string. |
"isEmpty" | The field is absent or empty. |
"isNotEmpty" | The field is present and non-empty. |
2.3 | Field Types
| Field | Description |
|---|---|
"country" | The viewer’s country, derived from their IP address. Use the full English country name (e.g. "Netherlands", "Belgium"). |
"domain" | The domain of the page embedding the player, derived from the HTTP Referer header. |
"ip" | The viewer’s IP address. Accepts IPv4, IPv6, and CIDR notation (e.g. "192.168.1.0/24"). |
"token" | A shared-secret token passed as a query parameter or request header. Tokens are managed via API keys with subtype "sharedsecret". |
2.4 | Ruleset Examples
Allow only Dutch and Belgian viewers:
{
"rulesets": [
{
"filters": [
{
"id": "rule1",
"field": "country",
"operator": "containsAnyOf",
"value": ["Netherlands", "Belgium"]
}
]
}
]
}Allow viewers from a specific domain OR with a valid token:
{
"rulesets": [
{
"filters": [
{
"id": "rule1",
"field": "domain",
"operator": "contains",
"value": "example.com"
}
]
},
{
"filters": [
{
"id": "rule2",
"field": "token",
"operator": "is",
"value": "mysecrettoken"
}
]
}
]
}Restrict to a specific IP range AND require a matching domain:
{
"rulesets": [
{
"filters": [
{
"id": "rule1",
"field": "ip",
"operator": "containsAnyOf",
"value": ["192.168.1.0/24", "10.0.0.0/8"]
},
{
"id": "rule2",
"field": "domain",
"operator": "contains",
"value": "intranet.example.com"
}
]
}
]
}3.0 | Retrieve List
Retrieves a list of all content protection policies for the publication.
3.1 | Query Parameters
| Parameter | Description |
|---|---|
limit | (integer) Maximum number of results to return. |
offset | (integer) Number of results to skip (for pagination). |
3.2 | Example Response
{
"type": "ContentProtectionPolicyList",
"publicationid": "754",
"count": 2,
"items": [
{
"type": "ContentProtectionPolicy",
"id": "42",
"name": "NL and BE only",
"status": "active"
},
{
"type": "ContentProtectionPolicy",
"id": "43",
"name": "Domain whitelist",
"status": "inactive"
}
]
}4.0 | Retrieve
Retrieves a single content protection policy by its id.
4.1 | Path Parameters
| Parameter | Description |
|---|---|
id | (string) The unique identifier of the content protection policy. |
5.0 | Create or Update
Creates a new policy or fully replaces an existing one. To create a new policy, use a new unique value for {id}. The full policy object must be provided in the request body.
5.1 | Path Parameters
| Parameter | Description |
|---|---|
id | (string) The unique identifier of the policy to create or replace. |
5.2 | Request Body
Provide a JSON object with the policy attributes described in section 1.2. The rulesets array is required.
5.3 | Example Request
{
"name": "NL and BE only",
"description": "Restrict playback to Netherlands and Belgium",
"status": "active",
"hideContent": false,
"labelPlacement": "center",
"backgroundColor": "#000000",
"rulesets": [
{
"filters": [
{
"id": "rule1",
"field": "country",
"operator": "containsAnyOf",
"value": ["Netherlands", "Belgium"]
}
]
}
]
}6.0 | Delete
Deletes a content protection policy. Policies that are currently assigned to a mediaclip or set as the publication default cannot be deleted until those references are removed.
6.1 | Path Parameters
| Parameter | Description |
|---|---|
id | (string) The unique identifier of the policy to delete. |
7.0 | Assigning Policies
7.1 | Assign to a Mediaclip
To apply a policy to an individual mediaclip, set the cpp field on the mediaclip object using the /sapi/mediaclip endpoint:
{
"cpp": "42"
}7.2 | Set as Publication Default
To set a policy as the default for all clips in a publication, update the cpp field on the publication configuration:
{
"cpp": "42"
}To remove the publication default, send a DELETE request to /sapi/publication/cpp.