> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SIP Authentication API

> Manage SIP credentials and IP Access Control Lists for securing inbound calls to your Plivo applications

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](/account/api/application/) by setting `sip_auth_type`, `ip_acl_uuid`, and `credential_uuid`.

For an overview of how SIP authentication works, see [SIP Authentication concepts](/voice/concepts/sip-authentication/).

### 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                                                     |

```json theme={null}
{
  "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](/voice/concepts/sip-authentication/#rate-limiting-and-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

<ParamField body="credential_uuid" type="string">
  Unique identifier for the credential.
</ParamField>

<ParamField body="username" type="string">
  The SIP username.
</ParamField>

<ParamField body="realm" type="string">
  Authentication realm. Default: `app.plivo.com`.
</ParamField>

<ParamField body="resource_uri" type="string">
  URI of the credential resource.
</ParamField>

<Note>
  Passwords are stored as one-way hashes (HA1) and are never returned in API responses.
</Note>

### Example Object

```json theme={null}
{
  "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

<ParamField body="username" type="string" required>
  3-64 characters. Allowed: alphanumeric, period (`.`), underscore (`_`), hyphen (`-`). Must be unique within your account.
</ParamField>

<ParamField body="password" type="string" required>
  8-128 characters. Must include at least one uppercase letter, one lowercase letter, and one digit.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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>"
    }'
  ```
</CodeGroup>

### Response (201 Created)

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/cred-abc123-def456/" \
    -u "<auth_id>:<auth_token>"
  ```
</CodeGroup>

***

## List All Credentials

Returns all SIP credentials for your account.

```
GET https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/
```

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/" \
    -u "<auth_id>:<auth_token>"
  ```
</CodeGroup>

***

## 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

<ParamField body="password" type="string" required>
  New password. Minimum 8 characters. Must include uppercase, lowercase, and digit.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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>"}'
  ```
</CodeGroup>

***

## Delete a Credential

Permanently delete a credential.

```
DELETE https://api.plivo.com/v1/Account/{auth_id}/SipAuth/Credential/{credential_uuid}/
```

<Warning>
  You cannot delete a credential currently assigned to an application. First remove the assignment by setting the application's `sip_auth_type` to empty (`""`).
</Warning>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.plivo.com/v1/Account/<auth_id>/SipAuth/Credential/cred-abc123-def456/" \
    -u "<auth_id>:<auth_token>"
  ```
</CodeGroup>

### 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

<ParamField body="ip_acl_uuid" type="string">
  Unique identifier for the IP ACL.
</ParamField>

<ParamField body="name" type="string">
  Friendly name for the IP ACL.
</ParamField>

<ParamField body="entries" type="array">
  List of IP entries. Each entry includes `entry_id`, `ip`, `cidr_prefix`, and `description`.
</ParamField>

<ParamField body="resource_uri" type="string">
  URI of the IP ACL resource.
</ParamField>

### Example Object

```json theme={null}
{
  "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

<ParamField body="name" type="string" required>
  Friendly name. 1-120 characters.
</ParamField>

<ParamField body="entries" type="array">
  Optional list of IP entries to add at creation time. Maximum 50 entries per ACL.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```
</CodeGroup>

### Response (201 Created)

```json theme={null}
{
  "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

<ParamField body="name" type="string">
  New name for the IP ACL.
</ParamField>

***

## 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}/
```

<Warning>
  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 (`""`).
</Warning>

### 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

<ParamField body="ip" type="string" required>
  Valid IPv4 address.
</ParamField>

<ParamField body="cidr_prefix" type="integer">
  CIDR prefix. Range: 0-32. Default: `32` (single host for IPv4). `0` allows all IPs.
</ParamField>

<ParamField body="description" type="string">
  Description of this entry. Up to 255 characters.
</ParamField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

### Response (201 Created)

```json theme={null}
{
  "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`

***

## Related

* [SIP Authentication concepts](/voice/concepts/sip-authentication/) — How SIP auth works, options, flow diagrams, and security best practices
* [Application API](/account/api/application/) — Assign credentials and IP ACLs to applications
* [Voice API: Make a Call](/voice/api/calls#make-a-call/) — Outbound SIP authentication via `sip_auth_username` and `sip_auth_password`
* [Dial XML](/voice/xml/routing#dial/) — Outbound SIP authentication via `sipAuthUsername` and `sipAuthPassword`