SIP / IP Access Control Lists API

Open API playground All endpoints

Named sets of source IPs or CIDR networks (acl_) that SIP trunks with authentication_type: IP authorise against. Attach one to many trunks and update it in a single place.

List IP access control lists

GET/api/v1/sip/ip-acls

List the IP access control lists in your account, newest first. Page with cursors (see the Pagination section in the overview).

Auth: x-api-key header

Parameters

Name	In	Type
`limit`	query	integer
`search`	query	string \| null
`cursor_after`	query	string \| null
`cursor_before`	query	string \| null

Responses

Status	Description
`200`	Successful Response
`400`	The pagination cursor is invalid or has expired.
`403`	The `x-api-key` header is missing or invalid.
`422`	The request body or query parameters failed validation.

Example response (200)

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "address_count": 0,
      "trunk_count": 0,
      "created_at": "date-time"
    }
  ],
  "next_cursor": "string",
  "previous_cursor": "string",
  "has_more": false
}

Create an IP access control list

POST/api/v1/sip/ip-acls

Create a named set of source IPs or CIDR networks that SIP trunks can authorise against. Reference the returned id as ip_acl_id when creating or updating a trunk with authentication_type: IP.

Auth: x-api-key header

Request body

namerequiredstring

Unique name for this ACL within your account.

addressesrequiredarray of object

At least one address or CIDR network.

addressrequiredstring

IPv4/IPv6 address or CIDR network, e.g. 203.0.113.7 or 203.0.113.0/24. CIDR networks are stored in canonical form (host bits stripped).

descriptionstring | null

Optional note, e.g. the carrier or PoP.

Example request

{
  "name": "string",
  "addresses": [
    {
      "address": "string",
      "description": "string"
    }
  ]
}

Responses

Status	Description
`201`	Successful Response
`403`	The `x-api-key` header is missing or invalid.
`409`	Another IP access control list in this account already uses that name.
`422`	The request body or query parameters failed validation.

Example response (201)

{
  "id": "string",
  "name": "string",
  "addresses": [],
  "trunk_count": 0,
  "created_at": "date-time",
  "updated_at": "date-time"
}

Retrieve an IP access control list

GET/api/v1/sip/ip-acls/{ip_acl_id}

Retrieve a single IP access control list, including its addresses.

Auth: x-api-key header

Parameters

Name	In	Type	Description
`ip_acl_id` required	path	string	The IP access control list identifier.

Responses

Status	Description
`200`	Successful Response
`403`	The `x-api-key` header is missing or invalid.
`404`	No IP access control list matches the supplied identifier for this account.
`422`	Validation Error

Example response (200)

{
  "id": "string",
  "name": "string",
  "addresses": [],
  "trunk_count": 0,
  "created_at": "date-time",
  "updated_at": "date-time"
}

Update an IP access control list

PATCH/api/v1/sip/ip-acls/{ip_acl_id}

Rename an ACL and/or replace its addresses. Supplying addresses replaces the entire set. Changes apply to every trunk using this ACL.

Auth: x-api-key header

Parameters

Name	In	Type	Description
`ip_acl_id` required	path	string	The IP access control list identifier.

Request body

namestring | null

addressesarray of object | null

When supplied, replaces the full set of addresses.

addressrequiredstring

IPv4/IPv6 address or CIDR network, e.g. 203.0.113.7 or 203.0.113.0/24. CIDR networks are stored in canonical form (host bits stripped).

descriptionstring | null

Optional note, e.g. the carrier or PoP.

Example request

{
  "name": "string",
  "addresses": [
    {
      "address": "string",
      "description": "string"
    }
  ]
}

Responses

Status	Description
`200`	Successful Response
`403`	The `x-api-key` header is missing or invalid.
`404`	No IP access control list matches the supplied identifier for this account.
`409`	Another IP access control list in this account already uses that name.
`422`	The request body or query parameters failed validation.

Example response (200)

{
  "id": "string",
  "name": "string",
  "addresses": [],
  "trunk_count": 0,
  "created_at": "date-time",
  "updated_at": "date-time"
}

Delete an IP access control list

DELETE/api/v1/sip/ip-acls/{ip_acl_id}

Delete an IP access control list. Refused with 409 while any SIP trunk still authorises against it, so a trunk can never be left without an auth source.

Auth: x-api-key header

Parameters

Name	In	Type	Description
`ip_acl_id` required	path	string	The IP access control list identifier.

Responses

Status	Description
`200`	Successful Response
`403`	The `x-api-key` header is missing or invalid.
`404`	No IP access control list matches the supplied identifier for this account.
`409`	The IP access control list is still attached to one or more SIP trunks. Point those trunks at another IP access control list (or at individual addresses) first.
`422`	Validation Error

Example response (200)

{
  "success": true,
  "message": "string"
}