Overview
The Geo & ISP restriction allows you to include or exclude certain Countries and/or ISPs from the Streamroot Products activation. With these set of APIs, it is possible to Whitelist or Blacklist Countries and/or ISPs where you want Streamroot Products (Mesh & Orchestrator) to be activated or deactivated depending on your business requirements.
Changes made to a Geo & ISP restriction take up to 10 minutes to be effective.
Authentication
API Key
To use our Data APIs you need to authenticate via API Key. You can get your API Keys from your Streamroot Dashboard in the Profile Section:
Customer ID
You will also need your Customer ID which can be found in the Company tab of the Profile section:
Authenticate via API Key
To use our data APIs you need to authenticate via API Key set in the Authorization HTTP header.
Once you have the key, simply add this header to your HTTP requests:
Authorization: API-Key {YOUR_API_KEY}
What is a Geo/ISP Restriction List
A Geo/ISP Restriction List can be created by defining the following fields:
Fields | Type | Description |
name | string | The name of the Geo ISP restriction list. Example: "Whitelist France". |
type | string | The type of the list. Possible values are "blacklist"and "whitelist" |
countries | string |
The list of countries where you plan to active/deactivate mesh network. The countries names are case insensitive: you could enter both uppercase and lowercase values and the name of the country must match |
isps | string |
The list of Internet Service Provider where you plan to active/deactivate mesh network. ISP names are case insensitive: you could enter both uppercase and lowercase value and We’ll verify that the names you entered are correct by making sure that they match |
<YOUR_CUSTOMER_ID> | String |
<YOUR_CUSTOMER_ID> is a string parameter which is the unique Customer ID that you are assigned for the Streamroot Product(s) that you use. It can be found in the Company Tab of the Profile Section. |
<YOUR_LIST_ID> | String | <YOUR_LIST_ID> is the geoblockingListId that is used to identify a Geo/ISP Restriction List. You can use this to point to particular list in an API end point. |
Empty Lists
While entering data in a field within a list, it is possible to have some fields where no data has been entered, i.e the field is empty. In that case, an empty list corresponds to missing field.
If a field within a list has no data in it, then it is considered to be a missing field.
Example:
This entry,
{
"name":"test empty ISP whitelist",
"type":"whitelist",
"countries": ["United Kingdom"],
"isp":[]
}
{
"name":"test empty ISP whitelist",
"type":"whitelist",
"countries":["United Kingdom"]
}
Relationships Between Countries and ISPs
When calling an API, it is important to keep in mind the relationships between the Countries and ISPs. The relationship differs depending on whether the list has been Blacklisted or Whitelisted. The fields are related in the following way:
Blacklist
- When defining a blacklist, we’ll exclude from the Orchestrator and/or mesh network users who belong to the list of Countries OR the list of ISPs
- When a blacklist rule is defined, only the clients whose IP matches the rule are deactivated, all others are activated.
Example
{
"name":"DNA_Config_1.1",
"type":"blacklist",
"countries":["France", "Italy"],
"isps":["Orange France Mobile", "Wind Tre"]
}
This list will result in all the viewers located in France & Italy (regardless of their ISP) as well as all viewers connected to the Orange France Mobile and Wind Tre (regardless of their country) being deactivated.
Whitelist
- When defining a blacklist, we’ll exclude from Orchestrator and/or mesh network users who belong to the list of Countries AND the list of ISPs
- When a whitelist rule is defined, only the clients whose IP matches the rule are activated, all the rest are deactivated.
Example
{
...
"type":"whitelist",
"countries":["United Kingdom", "Spain"],
"isps":["CenturyLink", "Wind Tre"]
}
This list will result in all the viewers located in United Kingdom & Spain who are connected to either Orange France Mobile or Wind Tre being deactivated.
Step by Step guide to setup a Geo/ISP Restriction List
In order to fully setup and implement a Geo/ISP Restriction List using our APIs, you can follow the following steps:
-
Create a Geo/ISP Restriction List
You can Create a Geo/ISP Restriction List using the following end-point.
POST api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists
With this end point, you define which countries and/or ISPs would be blacklisted or whitelisted.
- Attach a List to a Property
For a Geo/ISP Restriction list to be active, it needs to be attached to a property (See Property). It can be done using the following end points.
For Mesh
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/properties
For OrchestratorPOST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/compass/properties
- Get all properties
If you wish to attach your Geo/ISP Restriction List, you will need to know the name of the Property you wish to attach the list to. To see a list of all the Properties, you can use the following end points:
For Mesh
GET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/dna/properties
Response Example{ "name": "property_test", "activationRatio": 0, "superSeederRatio": 0, "detectRangeRequest": false, "geoblockingListId": "00000000-0000-0000-0000-000000000000", "networkActivation": { "wifiEthernetUpload": true, "wifiEthernetDownload": true, "cellularOtherUpload": false, "cellularOtherDownload": true }, "ssai": { "enabled": false, "provider": "", "options": null }, "enterprise": { "customStunUrls": [], "customSignalingUrl": "", "localNetworkOnly": false, "matching": false, "matchingMap": false, "matchingMask": false, "unknownSubnetAllow": false, "mask": 0 } }, { "name": "property_with_geo", "activationRatio": 1, "superSeederRatio": 1, "detectRangeRequest": false, "geoblockingListId": "00000000-0000-0000-0000-000000000000", "networkActivation": { "wifiEthernetUpload": true, "wifiEthernetDownload": true, "cellularOtherUpload": true, "cellularOtherDownload": true }, "ssai": { "enabled": false, "provider": "", "options": "" }, "enterprise": { "customStunUrls": [], "customSignalingUrl": "", "localNetworkOnly": false, "matching": false, "matchingMap": false, "matchingMask": false, "unknownSubnetAllow": false, "mask": 0 } }
For Orchestrator
GET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/compass/properties
Response Example
{ "name": "property_with_geo", "activationRatio": 1, "cdnListName": "", "geoblockingListId": "00000000-0000-0000-0000-000000000000", "cdnScoreProvider": { "name": "", "credentials": { "citrixCustomerID": 0, "citrixAppID": 0 } } }, { "name": "default", "activationRatio": 0, "cdnListName": "", "geoblockingListId": "00000000-0000-0000-0000-000000000000", "cdnScoreProvider": { "name": "", "credentials": { "citrixCustomerID": 0, "citrixAppID": 0 }
- Update the existing Property with your List
Now that you know which Property you wish to Update, you could do it by copying and pasting the Response Parameter into the Request body of the end point and just modifying thegeoblockingListId
to"geoblockingListId" : <YOUR_LIST_ID>
Mesh End PointPOST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/properties
Orchestrator End Point
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/compass/properties
Request Example
{ "name": "property_with_geo", "activationRatio": 1, "superSeederRatio": 1, "detectRangeRequest": false, "geoblockingListId": <YOUR_LIST_ID>, "networkActivation": { "wifiEthernetUpload": true, "wifiEthernetDownload": true, "cellularOtherUpload": true, "cellularOtherDownload": true }, "ssai": { "enabled": false, "provider": "", "options": "" },
- Get the Property the List is attached to.
You can get the Property that has the List attached by using the following end pointGET api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/dna/properties/{YOUR_PROPERTY_NAME}
- Edit the list
You can use the following end point to Edit the List.PUT api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}
- Delete the list
You can use the following end point to Delete the List.DELETE api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}
List of API endpoints
Given below is a list of all the API endpoints that can be used in order to set up Geo/ISP Restriction Lists:
POST // Create a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists
GET // Get all Geo/ISP Restriction Lists: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists
GET // Get one Geo/ISP Restriction List: api.streamroot.io/v3/customers/{{YOUR_CUSTOMER_ID}}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
PUT // Update a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
DEL // Delete a Geo/ISP Restriction List: api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
1. Create a Geo/ISP Restriction List
Allows to define a whitelist or blacklist of countries/ISPs to activate/deactivate the mesh network on.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists
For Blacklist
Request Body Example for Blacklist
{
"name":"DNA_Config_1.1",
"type":"blacklist",
"countries":["France", "Italy"],
"isps":["Orange France Mobile", "Wind Tre"]
}
{
"data": {
"countries": [
"France",
"Italy"
],
"customerId": <YOUR_CUSTOMER_ID>,
"id": <YOUR_LIST_ID>,
"isps": [
"Orange"
],
"name": "DNA_Config_black_test1",
"type": "blacklist"
}
}
For Whitelist:
{
...
"type":"whitelist",
"countries":["United Kingdom", "Spain"],
"isps":["CenturyLink", "Wind Tre"]
}
{
"data": {
"countries": [
"United Kingdom",
"Spain"
],
"customerId": <YOUR_CUSTOMER_ID>,
"id": <YOUR_LIST_ID>,
"isps": [
"CenturyLink",
"Wind Tre"
],
"name": "DNA_Config_white_test2",
"type": "whitelist"
}
}
2. Attach a Geo/ISP Restriction List to a Mesh Property
This allows you to attach a Geo/ISP Restriction Rule created by defining a Whitelist/Blacklist to a Property in Mesh.
For a Restriction list to be active, it needs to be attached to a Property .
This means that you can use different restriction lists for different properties.
Bear in mind that if you are using Orchestrator, you’ll need to attach your restriction list to your Orchestrator properties, and vice versa for Mesh.
Endpoint
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/dna/properties
Request Body Example
{
"name": "testGeoIspList",
"activationRatio": 1,
"superSeederRatio": 1,
"detectRangeRequests": true,
"networkActivation": {
"wifiEthernetUpload": true,
"wifiEthernetDownload": true,
"cellularOtherDownload": true,
"cellularOtherUpload": true
},
"ssai": {
"enabled": false,
"provider": "",
"options": ""
},
"geoblockingListId": <YOUR_LIST_ID>
}
Response Example
{
"name": "property1",
"activationRatio": 1,
"superSeederRatio": 1,
"detectRangeRequest": false,
"geoblockingListId": "<YOUR_LIST_ID>",
"networkActivation": {
"wifiEthernetUpload": true,
"wifiEthernetDownload": true,
"cellularOtherUpload": true,
"cellularOtherDownload": true
},
"ssai": {
"enabled": false,
"provider": "",
"options": ""
},
"enterprise": {
"customStunUrls": [],
"customSignalingUrl": "",
"localNetworkOnly": false,
"matching": false,
"matchingMap": false,
"matchingMask": false,
"unknownSubnetAllow": false,
"mask": 0
}
}
3. Attach a Geo/ISP Restriction List to an Orchestrator Property
This allows you to attach a Geo/ISP Restriction List created by defining a Whitelist/Blacklist to a Property in Mesh. Doing so allows you to implement the rule by calling the Orchestrator Property in your deliveryClientConfig
Each Property can only have one Geo/ISP Restriction List attached to it so as to avoid conflicts between different Restriction Lists.
End Point
POST api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/compass/properties
Request Example
{
"name": "testGeoIspList",
"activationRatio": 1,
"superSeederRatio": 1,
"detectRangeRequests": true,
"networkActivation": {
"wifiEthernetUpload": true,
"wifiEthernetDownload": true,
"cellularOtherDownload": true,
"cellularOtherUpload": true
},
"ssai": {
"enabled": false,
"provider": "",
"options": ""
},
"geoblockingListId": <YOUR_LIST_ID>
}
Response Example
{
"name": "testGeoIspList",
"activationRatio": 1,
"cdnListName": "",
"geoblockingListId": <YOUR_LIST_ID>,
"cdnScoreProvider": {
"name": "",
"credentials": {
"citrixCustomerID": 0,
"citrixAppID": 0
}
}
}
4. Get a particular Geo/ISP Restriction List
This can be used to get a particular Geo/ISP Restriction List
End Point
GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{{YOUR_LIST_ID}}
Response Example
{ "data": { "countries": [ "france" ], "customerId": <YOUR_CUSTOMER_ID>, "id": <YOUR_LIST_ID>, "name": "DNA_Config_1.1", "type": "blacklist" } }
5. Get all Geo/ISP Restriction Lists
This can be used to get all the active Geo/ISP Restriction Lists
End Point
GET api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists
Response Example
{ "data": [ { "countries": [ "france" ], "customerId": <YOUR_CUSTOMER_ID>, "id": <YOUR_LIST_ID>, "name": "DNA_Config_1.1", "type": "blacklist" }, { "countries": [ "france" ], "customerId": <YOUR_CUSTOMER_ID>, "id": <YOUR_LIST_ID>, "name": "DNA_Config_1.2", "type": "blacklist" } ] }
6. Update a Geo/ISP Restriction List
This can be used to update a particular Geo/ISP Restriction List
End Point
PUT api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}
Request Body Example
{
"name":"Whitelist (FR) (Orange France Mobile, SFR) - updated",
"type": "whitelist",
"countries" : ["France"],
"isps":["Orange France Mobile", "SFR"]
}
Response Example
7. Delete a Geo/ISP Restriction List
This can be used to delete a particular Geo/ISP Restriction List.
End Point
DELETE api.streamroot.io/v3/customers/{YOUR_CUSTOMER_ID}/geo-isp-restrictions/lists/{YOUR_LIST_ID}
Response Example
Errors
HTTP 400
{
"message": "invalid listId"
}
HTTP 500
{
"error": "empty activation rule is not allowed"
}