The IP Access Control Lists API lets you create and manage IP address whitelists for authenticating outbound SIP trunks.
API Endpoint
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/
The IP Access Control List Object
An IP Access Control List (IP ACL) contains a set of whitelisted IP addresses that can send SIP traffic to your outbound trunk.
Attributes
Unique identifier for the IP ACL.
Friendly name for the IP ACL.
List of whitelisted IP addresses.
Example Object
{
"ipacl_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
"name": "production-servers",
"ip_addresses": [
"192.168.1.1",
"192.168.1.2"
]
}
List All IP Access Control Lists
Get all IP ACLs for your account.
HTTP Request
GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|
limit | integer | No | 20 | Results per page (1-20) |
offset | integer | No | 0 | Pagination offset |
Response
Unique identifier for the API request.
Pagination metadata: limit (results per page), offset (items skipped), total_count (total matching IP access control lists).
{
"api_id": "a04ad809-3b78-4bbe-9baf-acfc7800b10f",
"meta": {
"limit": 20,
"offset": 0,
"total_count": 109,
"previous": null,
"next": "v1/Account/{auth_id}/Zentrunk/IPAccessControlList/?limit=20&offset=20"
},
"objects": [
{
"ipacl_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
"name": "production-servers",
"ip_addresses": ["192.168.1.1", "192.168.1.2"]
},
{
"ipacl_uuid": "a19c4773-4ae6-4b75-92ea-9cf3ea4227d7",
"name": "staging-servers",
"ip_addresses": ["10.0.0.1", "10.0.0.2"]
}
]
}
Example
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
# List all IP ACLs
response = client.zentrunk.ip_access_control_lists.list()
print(response)
# List with pagination
response = client.zentrunk.ip_access_control_lists.list(limit=10, offset=0)
print(response)
const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');
// List all IP ACLs
client.zentrunk.ipAccessControlLists.list()
.then(response => console.log(response));
// List with pagination
client.zentrunk.ipAccessControlLists.list({limit: 10, offset: 0})
.then(response => console.log(response));
Retrieve an IP Access Control List
Get details of a specific IP ACL.
HTTP Request
GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/{ipacl_uuid}/
Response
Unique identifier for the IP ACL.
Friendly name for the IP ACL.
List of whitelisted IP addresses.
{
"ipacl_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
"name": "production-servers",
"ip_addresses": [
"192.168.1.1",
"192.168.1.2"
]
}
Example
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.ip_access_control_lists.get('f19c4773-4ae6-4b75-92ea-9cf3ea4227d6')
print(response)
const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');
client.zentrunk.ipAccessControlLists.get('f19c4773-4ae6-4b75-92ea-9cf3ea4227d6')
.then(response => console.log(response));
Create an IP Access Control List
Create a new IP whitelist for SIP trunk authentication.
HTTP Request
POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|
name | string | No | - | Friendly name for the IP ACL |
ip_addresses | array | Yes | - | Array of IP addresses to whitelist |
Response
Unique identifier for the API request.
Status of the request. Returns IP access control list created successfully. on a successful creation.
Unique identifier for the IP ACL.
{
"api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
"message": "IP access control list created successfully.",
"ipacl_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}
Error Codes
| Code | Description |
|---|
| 400 | Invalid request parameters |
| 401 | Authentication failed |
| 422 | Missing required parameters (ip_addresses) |
Example
curl -i --user AUTH_ID:AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"name": "production-servers",
"ip_addresses": ["192.168.0.1", "192.168.0.2", "10.0.0.1"]
}' \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.ip_access_control_lists.create(
name='production-servers',
ip_addresses=['192.168.0.1', '192.168.0.2', '10.0.0.1']
)
print(response)
const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');
client.zentrunk.ipAccessControlLists.create({
name: 'production-servers',
ipAddresses: ['192.168.0.1', '192.168.0.2', '10.0.0.1']
}).then(response => console.log(response));
Update an IP Access Control List
Modify an existing IP ACL’s name or IP addresses.
HTTP Request
POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/{ipacl_uuid}/
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|
name | string | No | - | New friendly name |
ip_addresses | array | No | - | New list of IP addresses (replaces existing) |
Response
Unique identifier for the API request.
Status of the request. Returns IP access control list updated successfully. on a successful update.
Unique identifier for the IP ACL.
{
"api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
"message": "IP access control list updated successfully.",
"ipacl_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}
Updating ip_addresses replaces the entire list. Include all IP addresses you want whitelisted.
Example
curl -i --user AUTH_ID:AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"name": "updated-servers",
"ip_addresses": ["192.168.0.1", "192.168.0.2", "192.168.0.3"]
}' \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.ip_access_control_lists.update(
'f19c4773-4ae6-4b75-92ea-9cf3ea4227d6',
name='updated-servers',
ip_addresses=['192.168.0.1', '192.168.0.2', '192.168.0.3']
)
print(response)
const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');
client.zentrunk.ipAccessControlLists.update('f19c4773-4ae6-4b75-92ea-9cf3ea4227d6', {
name: 'updated-servers',
ipAddresses: ['192.168.0.1', '192.168.0.2', '192.168.0.3']
}).then(response => console.log(response));
Delete an IP Access Control List
Permanently delete an IP ACL.
HTTP Request
DELETE https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/{ipacl_uuid}/
Response
HTTP 204 No Content
Deleting an IP ACL that is attached to an active trunk will break authentication for that trunk.
Example
curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/IPAccessControlList/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.ip_access_control_lists.delete('f19c4773-4ae6-4b75-92ea-9cf3ea4227d6')
print(response)
const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');
client.zentrunk.ipAccessControlLists.delete('f19c4773-4ae6-4b75-92ea-9cf3ea4227d6')
.then(response => console.log(response));
Usage with Trunks
After creating an IP ACL, attach it to an outbound trunk.
Example
curl -i --user AUTH_ID:AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"name": "outbound-trunk",
"trunk_direction": "outbound",
"ipacl_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}' \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.zentrunk.trunks.create(
name='outbound-trunk',
trunk_direction='outbound',
ipacl_uuid='f19c4773-4ae6-4b75-92ea-9cf3ea4227d6'
)
print(response)
const plivo = require('plivo');
const client = new plivo.Client('<auth_id>', '<auth_token>');
client.zentrunk.trunks.create({
name: 'outbound-trunk',
trunkDirection: 'outbound',
ipaclUuid: 'f19c4773-4ae6-4b75-92ea-9cf3ea4227d6'
}).then(response => console.log(response));
IP ACL vs Credentials
| Method | Use Case |
|---|
| IP ACL | When your PBX has static IP addresses. Simpler setup, no password management. |
| Credentials | When your PBX has dynamic IPs or you need additional security. Uses SIP digest authentication. |
- Trunks - Create and manage SIP trunks
- Credentials - Alternative authentication via username/password
