Skip to main content
  • What: Secure your Plivo voice applications by controlling who can place inbound SIP calls, and authenticate outbound calls to SIP providers that require credentials
  • How: Assign an IP ACL, SIP credential, or both to your Plivo Application via the Application API. For outbound, pass credentials in Dial XML or the Make Call API.
  • Key concept: Inbound auth resolves from the SIP Request-URI (sip:{app_id}@app.plivo.com), not the To header. Your SIP provider must send INVITEs to the application’s SIP URI for auth to apply.
  • Note: Rate limiting protects against brute-force: 10 failed attempts from the same IP in 60 seconds triggers a 60-second lockout.
SIP Authentication lets you secure your Plivo voice applications by controlling who can place inbound SIP calls and by authenticating outbound calls to SIP trunks that require credentials.
Request-URI requirement: For inbound SIP authentication to apply, the Request-URI of the INVITE must be sip:{app_id}@app.plivo.com. Plivo resolves the application from the Request-URI user part, not from the To header. If your SIP provider places a phone number in the Request-URI, configure the provider to send INVITEs to the application’s SIP URI instead.

​
Three Authentication Capabilities

CapabilityDirectionWhat It Does
Inbound AuthenticationInboundRestrict who can call your Plivo app using IP-based access control, SIP digest credentials, or both
Outbound Authentication (Dial XML)OutboundProvide SIP credentials in your Dial XML so Plivo can authenticate with external SIP providers
Outbound Authentication (Make Call API)OutboundSame as above, but credentials are passed via the Make Call REST API instead of XML

​
Inbound Authentication

Inbound authentication protects your Plivo Application from unauthorized SIP calls. You configure it by assigning a credential, IP ACL, or both to your Application.

​
Three Options

Optionsip_auth_typeWhen to Use
IP ACL onlyip_aclCalls only allowed from whitelisted IP addresses or CIDR ranges. Fastest — no challenge/response handshake.
Credential onlycredentialCallers must authenticate with username/password via SIP digest auth (407 challenge). Use when source IPs are dynamic.
Both (IP ACL + Credential)ip_acl_and_credentialCaller must pass both the IP check AND provide valid credentials. Maximum security.

​
How Inbound Authentication Works

Caller sends SIP INVITE to sip:{app_id}@app.plivo.com
   |
   v
Plivo resolves app from Request-URI user part
   |
   v
Plivo checks auth config for the app
   |
   |-- IP ACL configured?
   |     Check caller's IP against allowed list
   |     Not in list -> Call rejected (403)
   |
   |-- Credential configured?
   |     Send 407 Proxy Authentication Required
   |     Caller responds with digest credentials
   |     Wrong credentials -> Call rejected (403)
   |
   |-- Both configured?
   |     IP check first, then credential check
   |     Either fails -> Call rejected (403)
   |
   v
Authentication passed -> Call routed to your app's answer_url

​
Setup Steps

1

Create a credential and/or IP ACL

Use the SIP Authentication API to create:
  • A SIP credential with username and password (POST /SipAuth/Credential/)
  • An IP ACL with a name (POST /SipAuth/IpAccessControlList/), then add IP entries (POST /SipAuth/IpAccessControlList/{uuid}/Entry/)
2

Assign to your Application

Update your Application via the Application API by setting sip_auth_type and the corresponding credential_uuid and/or ip_acl_uuid.
3

Test

Make a test SIP call to your application’s SIP URI (sip:{app_id}@app.plivo.com) and verify it succeeds with valid auth and fails without.To confirm auth is running, check for the SIPAuthType parameter in your answer_url callback (see Callback Parameters below).

​
Callback Parameters

When authentication succeeds, your answer_url callback receives these additional parameters:
ParameterDescription
SIPAuthTypeAuth method used: ip_acl, credential, or ip_acl_and_credential
SIPAuthUserAuthenticated SIP username (credential auth only)
SIPSourceIPThe caller’s source IP address
If you don’t see SIPAuthType in your callback, auth is not running. The most common cause is the SIP provider placing a phone number in the Request-URI instead of your app_id — see the Warning at the top of this page.

​
Rate Limiting

To protect against brute-force attacks, Plivo enforces rate limiting on failed authentication attempts:
  • 10 failed attempts from the same source IP within 60 seconds triggers automatic lockout
  • During lockout, all calls from that IP receive 403 Forbidden — even with correct credentials
  • The lockout resets automatically after the 60-second window expires

​
Outbound Authentication

When making outbound calls to SIP providers that require authentication (responds with 401/407 challenge), provide credentials so Plivo can complete the digest handshake on your behalf.

​
Before You Start

Confirm with your SIP provider:
  • Username and password for digest authentication
  • Whether they use IP-based auth instead — if so, you don’t need to pass credentials; instead ask the provider to whitelist Plivo’s media server IPs
  • Realm — Plivo handles realm matching automatically from the 407 response, so you generally don’t need to configure this

​
How Outbound Authentication Works

1

Plivo sends INVITE

Plivo sends a SIP INVITE to the destination (e.g., sip:endpoint@provider.example.com).
2

Provider challenges

Provider responds with 407 Proxy Authentication Required (or 401 Unauthorized).
3

Plivo computes digest

Plivo automatically computes the digest response using the credentials you provided.
4

Plivo re-sends INVITE

Plivo re-sends the INVITE with authentication headers.
5

Call connects

Provider accepts and the call connects. If authentication fails, the call ends with hangup cause sip_auth_failed (code 4240).

​
Option 1: Dial XML

Pass credentials on the <User> element in your answer URL XML: 
<Response>
    <Dial>
        <User sipAuthUsername="<sip_username>" sipAuthPassword="<sip_password>">
            sip:endpoint@provider.example.com
        </User>
    </Dial>
</Response>

​
Option 2: Make Call API

Pass credentials when initiating an outbound call via the API: 
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/Call/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "sip:endpoint@provider.example.com",
    "answer_url": "https://example.com/answer.xml",
    "sip_auth_username": "<sip_username>",
    "sip_auth_password": "<sip_password>"
  }'
sip_auth_username and sip_auth_password are only accepted when to is a SIP URI.

​
Use Case: Transfer to Human Agent

A common use case is transferring an AI-handled call to a human agent. The agent typically sits behind a softphone, contact center software, or PBX that requires SIP authentication. See Transfer to Human Agent for the full workflow.

​
Hangup Causes

When a call fails due to authentication, the CDR and hangup callback include a specific cause:
HangupCauseNameCodeDirectionCallStatusMeaning
sip_auth_failed4210InboundfailedCaller failed IP ACL or credential check
sip_auth_failed4240OutboundfailedProvided credentials were rejected by the remote provider
sip_auth_timeout4250OutboundtimeoutRemote provider did not respond to the authentication attempt
These values appear in the HangupCauseName / PlivoHangupCause fields. CallStatus stays within the standard set (completed, busy, no-answer, failed, timeout, cancel).

​
Validation Limits

ResourceLimit
IP ACLs per account100
Credentials per account200
Entries per IP ACL50
Username3-64 characters. Allowed: letters, digits, ., _, -
Password12-128 characters. Must include at least one uppercase, one lowercase, and one digit
IP ACL nameUp to 120 characters
Entry descriptionUp to 255 characters
CIDR prefix0-32 for IPv4; 0-128 for IPv6

​
Security

Plivo treats SIP credentials with the same care as account credentials:
  • Passwords are stored as one-way hashes (HA1) — never in plaintext
  • Passwords are never returned in any API response
  • SIP auth credentials are never included in CDR data or callback parameters
  • Auth headers are stripped before forwarding calls externally
  • Failed authentication attempts are rate-limited to prevent brute-force attacks
  • All internal communication uses encrypted channels
  • Always use HTTPS for your answer_url — Plivo sends callback parameters (including SIPAuthUser) over HTTP to your server
  • Validate callbacks with X-Plivo-Signature — verify that callbacks are genuinely from Plivo using Signature Validation
  • Beware of shared IPs — if your SIP provider is on carrier-grade NAT or a shared-IP platform, IP ACL alone may not be sufficient. Use ip_acl_and_credential for defense in depth.
  • Monitor auth failures — track sip_auth_failed hangup causes in your call logs to detect unauthorized access attempts

​
Troubleshooting

SymptomLikely CauseFix
All calls get 403 ForbiddenIP not in ACL, or wrong credentialsVerify the caller’s IP matches an ACL entry. For credentials, check username/password match exactly.
Calls succeed but no SIPAuthType in callbackRequest-URI doesn’t contain your app_idConfigure your SIP provider to send INVITEs to sip:{app_id}@app.plivo.com, not to a phone number.
Digest auth fails (sip_auth_failed) despite correct credentialsRealm mismatch or provider uses a non-standard challengePlivo handles realm automatically. Contact the provider to confirm they send a standard 407/401 challenge.
All calls fail after working fineRate limit lockout (10 failures in 60s)Wait 60 seconds for lockout to expire. Fix the underlying auth issue.
Outbound call fails with sip_auth_failed (code 4240)Remote provider rejected your credentialsVerify username/password with the provider. Check if the provider uses IP auth instead of digest.
Outbound call fails with sip_auth_timeout (code 4250)Remote provider didn’t respond to the auth challengeProvider may be unreachable. Check network connectivity and provider status.

​
End-to-End Examples

​
Example 1: Secure inbound calls with IP whitelist

# 1a. Create IP ACL
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: {"ip_acl_uuid": "acl-abc123"}

# 1b. Add an entry
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": "198.51.100.5", "cidr_prefix": 32, "description": "Remote PBX"}'

# 2. Assign to app
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/Application/<app_id>/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"sip_auth_type": "ip_acl", "ip_acl_uuid": "acl-abc123"}'

# 3. Call from allowed IP -> connects
# 4. Call from other IP -> 403 Forbidden

​
Example 2: Secure inbound calls with digest credentials

# 1. Create credential
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": "pbx-user", "password": "<your_password>"}'
# Response: {"credential_uuid": "cred-def456"}

# 2. Assign to app
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/Application/<app_id>/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"sip_auth_type": "credential", "credential_uuid": "cred-def456"}'

# 3. Configure your PBX/SIP client with username "pbx-user" and password from step 1
# 4. Call -> 407 challenge -> PBX responds with credentials -> call connects

​
Example 3: Outbound call to an authenticated SIP trunk

curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/Call/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155551234",
    "to": "sip:+14155559999@trunk.provider.com",
    "answer_url": "https://example.com/answer.xml",
    "sip_auth_username": "<sip_username>",
    "sip_auth_password": "<sip_password>"
  }'
Or via Dial XML in your answer URL: 
<Response>
    <Dial>
        <User sipAuthUsername="<sip_username>" sipAuthPassword="<sip_password>">
            sip:+14155559999@trunk.provider.com
        </User>
    </Dial>
</Response>

​
FAQ

​
Can I use both IP ACL and credential auth together?

Yes. Set sip_auth_type to ip_acl_and_credential. The caller must pass the IP check AND provide valid credentials.

​
What happens if I delete a credential or IP ACL that’s assigned to an app?

The API returns a 400 error. You must first remove the assignment from the application by setting sip_auth_type to empty ("").

​
Can I update the password on an existing credential?

Yes. Send a POST to the credential’s URL with just the password field. The username remains unchanged. The change takes effect immediately for all applications using that credential.

​
What realm is used for digest authentication?

The default realm is app.plivo.com. This is included in the 407 challenge response. Plivo handles realm matching automatically during the handshake.

​
Can I set different auth for different apps?

Yes. Each application has its own sip_auth_type, ip_acl_uuid, and credential_uuid configuration. You can reuse the same credential or IP ACL across multiple apps.

​
Does changing an IP ACL take effect immediately?

Yes. Adding or removing entries from an IP ACL takes effect immediately for all applications using that ACL.

​
Can I use a hostname in an IP ACL?

No. IP ACL entries require a valid IPv4 or IPv6 address. Hostnames are not supported.

​
Is IPv6 supported?

Yes. IP ACL entries support IPv6 addresses with CIDR prefix range 0-128.

​
Can one app have multiple IP ACLs?

No. Each application can have at most one IP ACL and one credential assigned. To allow multiple IP ranges, add multiple entries to a single ACL (up to 50 entries).

​
What’s the latency impact of SIP authentication?

IP ACL adds negligible latency (simple lookup). Credential auth adds one round-trip for the 407 challenge/response (typically under 50ms on well-connected networks).

​
Can I rotate a password without call interruption?

Yes. Update the password on the credential via the API, then update your SIP client with the new password. There may be a brief window where calls using the old password fail.