Skip to main content
The SIP Authentication API lets you create and manage two resources used to secure inbound calls to your Plivo applications:
  • SIP Credentials — username and password pairs used for SIP digest authentication
  • IP Access Control Lists (IP ACLs) — lists of trusted IP addresses or CIDR ranges allowed to call your application
Once created, assign these resources to an application via the Application API by setting sip_auth_type, ip_acl_uuid, and credential_uuid. For an overview of how SIP authentication works, see SIP Authentication concepts.

​
Account Quotas

ResourceLimit
IP ACLs per account100
Credentials per account200
Entries per IP ACL50

​
Error Responses

All endpoints return standard HTTP status codes with a JSON error body:
StatusMeaning
400Validation error (missing field, invalid format, exceeds limits)
404Resource not found
409Conflict (duplicate username, resource in use)
429Rate limited
{
  "api_id": "...",
  "error": "This credential is currently assigned to an application. Remove the assignment first by setting sip_auth_type to empty."
}
API Endpoint 
https://api.plivo.com/v1/Account/{auth_id}/SipAuth/

​
The Credential Object

A SIP credential is a username/password pair used for SIP digest authentication.

​
Attributes

​
credential_uuid
string
Unique identifier for the credential.
​
username
string
The SIP username.
​
realm
string
Authentication realm. Default: app.plivo.com.
​
resource_uri
string
URI of the credential resource.
Passwords are stored as one-way hashes (HA1) and are never returned in API responses.

​
Example Object

{
  "credential_uuid": "cred-abc123-def456",
  "username": "sipuser1",
  "realm": "app.plivo.com",
  "resource_uri": "/v1/Account/{auth_id}/SipAuth/Credential/cred-abc123-def456/"
}

​
Create a Credential

Create a new SIP credential. 
POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/

​
Arguments

​
username
string
required
3-64 characters. Allowed: alphanumeric, period (.), underscore (_), hyphen (-). Must be unique within your account.
​
password
string
required
12-128 characters. Must include at least one uppercase letter, one lowercase letter, and one digit.

​
Example

curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/" \
  -u "<auth_id>:<auth_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "sipuser1",
    "password": "<your_password>"
  }'

​
Response (201 Created)

{
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949",
  "credential_uuid": "cred-abc123-def456",
  "username": "sipuser1",
  "realm": "app.plivo.com",
  "resource_uri": "/v1/Account/{auth_id}/SipAuth/Credential/cred-abc123-def456/"
}

​
Retrieve a Credential

Get details of a specific credential. 
GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/{credential_uuid}/

​
Example

curl "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/cred-abc123-def456/" \
  -u "<auth_id>:<auth_token>"

​
List All Credentials

Returns all SIP credentials for your account. 
GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/

​
Example

curl "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/" \
  -u "<auth_id>:<auth_token>"

​
Update a Credential

Update the password on an existing credential. The username cannot be changed. 
POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/{credential_uuid}/

​
Arguments

​
password
string
required
New password. Minimum 12 characters. Must include uppercase, lowercase, and digit.

​
Example

curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/cred-abc123-def456/" \
  -u "<auth_id>:<auth_token>" \
  -H "Content-Type: application/json" \
  -d '{"password": "<new_password>"}'

​
Delete a Credential

Permanently delete a credential. 
DELETE https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/{credential_uuid}/
You cannot delete a credential currently assigned to an application. First remove the assignment by setting the application’s sip_auth_type to empty ("").

​
Example

curl -X DELETE "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/cred-abc123-def456/" \
  -u "<auth_id>:<auth_token>"

​
Response

HTTP Status Code: 204

​
The IP Access Control List Object

An IP ACL is a list of trusted IP addresses or CIDR ranges allowed to make inbound calls to your application.

​
Attributes

​
ip_acl_uuid
string
Unique identifier for the IP ACL.
​
name
string
Friendly name for the IP ACL.
​
entries
array
List of IP entries. Each entry includes entry_id, ip, cidr_prefix, and description.
​
resource_uri
string
URI of the IP ACL resource.

​
Example Object

{
  "ip_acl_uuid": "acl-abc123",
  "name": "Office Network",
  "entries": [
    {
      "entry_id": "entry-001",
      "ip": "203.0.113.10",
      "cidr_prefix": 32,
      "description": "Primary PBX"
    }
  ],
  "resource_uri": "/v1/Account/{auth_id}/SipAuth/IpAccessControlList/acl-abc123/"
}

​
Create an IP ACL

Create a new IP Access Control List. 
POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/

​
Arguments

​
name
string
required
Friendly name. 1-120 characters.
​
entries
array
Optional list of IP entries to add at creation time. Maximum 50 entries per ACL.

​
Example

curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/IpAccessControlList/" \
  -u "<auth_id>:<auth_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Office Network"}'

​
Response (201 Created)

{
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949",
  "ip_acl_uuid": "acl-abc123"
}

​
Retrieve an IP ACL

Get details of a specific IP ACL, including all entries. 
GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/

​
List All IP ACLs

Returns all IP ACLs for your account. 
GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/

​
Update an IP ACL

Update the name of an existing IP ACL. 
POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/

​
Arguments

​
name
string
New name for the IP ACL.

​
Delete an IP ACL

Permanently delete an IP ACL and all its entries. 
DELETE https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/
You cannot delete an IP ACL currently assigned to an application. First remove the assignment by setting the application’s sip_auth_type to empty ("").

​
Response

HTTP Status Code: 204

​
Add an Entry to an IP ACL

Add a new IP address or CIDR range to an existing IP ACL. Maximum 50 entries per ACL. 
POST https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/Entry/

​
Arguments

​
ip
string
required
Valid IPv4 or IPv6 address.
​
cidr_prefix
integer
CIDR prefix. Range: 0-32 for IPv4, 0-128 for IPv6. Default: 32 (single host for IPv4). 0 allows all IPs.
​
description
string
Description of this entry. Up to 255 characters.

​
Example

curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/IpAccessControlList/acl-abc123/Entry/" \
  -u "<auth_id>:<auth_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "203.0.113.10",
    "cidr_prefix": 32,
    "description": "Primary PBX"
  }'

​
Response (201 Created)

{
  "api_id": "5a9fcb68-582d-11e1-86da-6ff39efcb949",
  "entry_id": "entry-001"
}

​
Remove an Entry from an IP ACL

Permanently delete an entry from an IP ACL. 
DELETE https://api.plivo.com/v1/Account/{auth_id}/SipAuth/IpAccessControlList/{ip_acl_uuid}/Entry/{entry_id}/

​
Response

HTTP Status Code: 204