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

# Credentials

> Manage SIP credentials for digest authentication on outbound trunks

The Credentials API lets you create and manage username/password pairs for SIP digest authentication on outbound trunks.

## API Endpoint

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

***

## The Credentials Object

A credentials object contains username and password for SIP digest authentication when your PBX sends calls to Plivo.

### Attributes

**credential\_uuid** `string`

Unique identifier for the credentials.

**name** `string`

Friendly name for the credentials.

**username** `string`

Username for SIP authentication. Must be 5 to 20 characters, containing only alphanumeric characters.

**password** `string`

Password for SIP authentication (only set on create/update, never returned in responses). Must be 5 to 20 characters, containing only alphanumeric characters and the special characters `~!@#$%^&*()_+`, with at least one special character.

### Example Object

```json theme={null}
{
  "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
  "name": "my-credentials",
  "username": "sipuser1"
}
```

> [!NOTE]
>
> The password is never returned in API responses for security. It is only used when creating or updating credentials.

***

## List All Credentials

Get all credentials for your account.

### HTTP Request

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

### Query Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `limit` | integer | No | 20 | Results per page (1-20) |
| `offset` | integer | No | 0 | Pagination offset |

### Response

**api\_id** `string`

Unique identifier for the API request.

**meta** `object`

Pagination metadata: `limit` (results per page), `offset` (items skipped), `total_count` (total matching credentials).

**objects** `array`

Array of credentials objects — see [The Credentials Object](#the-credentials-object).

```json theme={null}
{
  "api_id": "a04ad809-3b78-4bbe-9baf-acfc7800b10f",
  "meta": {
    "limit": 20,
    "offset": 0,
    "total_count": 109,
    "previous": null,
    "next": "v1/Account/{auth_id}/Zentrunk/Credential/?limit=20&offset=20"
  },
  "objects": [
    {
      "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
      "name": "production-credentials",
      "username": "sipuser123"
    },
    {
      "credential_uuid": "c4773-4ae6-4b75-92ea-9cf3ea4227d6",
      "name": "staging-credentials",
      "username": "sipuser456"
    }
  ]
}
```

### Example

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/
```

***

## Retrieve Credentials

Get details of specific credentials.

### HTTP Request

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

### Response

**credential\_uuid** `string`

Unique identifier for the credentials.

**name** `string`

Friendly name for the credentials.

**username** `string`

Username for SIP authentication.

```json theme={null}
{
  "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
  "name": "my-credentials",
  "username": "sipuser1"
}
```

### Example

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
```

***

## Create Credentials

Create a new credential set for SIP digest authentication.

### HTTP Request

`POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/`

### Request Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | string | No | - | Friendly name for the credentials |
| `username` | string | Yes | - | Username for SIP authentication. Must be 5 to 20 characters, alphanumeric only |
| `password` | string | Yes | - | Password for SIP authentication. Must be 5 to 20 characters, containing only alphanumeric characters and the special characters `~!@#$%^&*()_+`, with at least one special character |

### Response

**api\_id** `string`

Unique identifier for the API request.

**message** `string`

Status of the request. Returns `credential created successfully.` on a successful creation.

**credential\_uuid** `string`

Unique identifier for the credentials.

```json theme={null}
{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "credential created successfully.",
  "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}
```

### Error Codes

| Code | Description |
| - | - |
| 400 | Invalid request parameters (for example, the username or password doesn't meet the format requirements) |
| 401 | Authentication failed |
| 422 | Missing required parameters (username or password) |

### Example

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "production-credentials",
      "username": "sipuser123",
      "password": "securepassword123!"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/
```

***

## Update Credentials

Modify an existing credential's name, username, or password.

### HTTP Request

`POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/{credential_uuid}/`

### Request Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | string | No | - | New friendly name |
| `username` | string | No | - | New username. Must be 5 to 20 characters, alphanumeric only |
| `password` | string | No | - | New password. Must be 5 to 20 characters, containing only alphanumeric characters and the special characters `~!@#$%^&*()_+`, with at least one special character |

### Response

**api\_id** `string`

Unique identifier for the API request.

**message** `string`

Status of the request. Returns `Credential updated successfully.` on a successful update.

**credential\_uuid** `string`

Unique identifier for the credentials.

```json theme={null}
{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "Credential updated successfully.",
  "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}
```

### Example

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"username": "newuser", "password": "newpassword123!"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
```

***

## Delete Credentials

Permanently delete credentials.

### HTTP Request

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

### Response

HTTP 204 No Content

> [!WARNING]
>
> Deleting credentials that are attached to an active trunk will break authentication for that trunk.

### Example

```bash cURL theme={null}
curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/{credential_uuid}/
```

***

## Usage with Trunks

After creating credentials, attach them to an outbound trunk.

### Example

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
      "name": "outbound-trunk",
      "trunk_direction": "outbound",
      "credential_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/
```

***

## Related

* [Trunks](https://plivo.com/docs/sip-trunking/api/trunks.md) - Create and manage SIP trunks
* [IP Access Control Lists](https://plivo.com/docs/sip-trunking/api/ip-access-control-lists.md) - Alternative authentication via IP whitelisting