SIP Authentication API

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

Resource	Limit
IP ACLs per account	100
Credentials per account	200
Entries per IP ACL	50

Error Responses

All endpoints return standard HTTP status codes with a JSON error body:

Status	Meaning
`400`	Validation error (missing field, invalid format, exceeds limits)
`404`	Resource not found
`409`	Conflict (duplicate username, resource in use)
`429`	Rate limited

string

Unique identifier for the API request.

string

Human-readable description of the error.

{
  "api_id": "...",
  "error": "This credential is currently assigned to an application. Remove the assignment first by setting sip_auth_type to empty."
}

If your integration is receiving unexpected 403 responses on inbound calls, see the Rate-limit lockout section on the SIP Authentication concept page. 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

string

Unique identifier for the credential.

string

The SIP username.

string

Authentication realm. Default: app.plivo.com.

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

string

required

3-64 characters. Allowed: alphanumeric, period (.), underscore (_), hyphen (-). Must be unique within your account.

string

required

8-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)

string

Unique identifier for the API request.

string

Unique identifier for the credential.

string

The SIP username.

string

Authentication realm. Default: app.plivo.com.

string

URI of the credential resource.

{
  "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

string

required

New password. Minimum 8 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

string

Unique identifier for the IP ACL.

string

Friendly name for the IP ACL.

array

List of IP entries. Each entry includes entry_id, ip, cidr_prefix, and description.

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

string

required

Friendly name. 1-120 characters.

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)

string

Unique identifier for the API request.

string

Unique identifier for the IP ACL.

{
  "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

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

string

required

Valid IPv4 address.

integer

CIDR prefix. Range: 0-32. Default: 32 (single host for IPv4). 0 allows all IPs.

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)

string

Unique identifier for the API request.

string

Unique identifier for the IP ACL entry.

{
  "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

SIP Authentication concepts — How SIP auth works, options, flow diagrams, and security best practices
Application API — Assign credentials and IP ACLs to applications
Voice API: Make a Call — Outbound SIP authentication via sip_auth_username and sip_auth_password
Dial XML — Outbound SIP authentication via sipAuthUsername and sipAuthPassword

​Account Quotas

​Error Responses

​The Credential Object

​Attributes

​Example Object

​Create a Credential

​Arguments

​Example

​Response (201 Created)

​Retrieve a Credential

​Example

​List All Credentials

​Example

​Update a Credential

​Arguments

​Example

​Delete a Credential

​Example

​Response

​The IP Access Control List Object

​Attributes

​Example Object

​Create an IP ACL

​Arguments

​Example

​Response (201 Created)

​Retrieve an IP ACL

​List All IP ACLs

​Update an IP ACL

​Arguments

​Delete an IP ACL

​Response

​Add an Entry to an IP ACL

​Arguments

​Example

​Response (201 Created)

​Remove an Entry from an IP ACL

​Response

​Related

Account Quotas

Error Responses

The Credential Object

Attributes

Example Object

Create a Credential

Arguments

Example

Response (201 Created)

Retrieve a Credential

Example

List All Credentials

Example

Update a Credential

Arguments

Example

Delete a Credential

Example

Response

The IP Access Control List Object

Attributes

Example Object

Create an IP ACL

Arguments

Example

Response (201 Created)

Retrieve an IP ACL

List All IP ACLs

Update an IP ACL

Arguments

Delete an IP ACL

Response

Add an Entry to an IP ACL

Arguments

Example

Response (201 Created)

Remove an Entry from an IP ACL

Response

Related