Credentials - Plivo

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

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

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.

Example

cURL

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.

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

Example

cURL

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.

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

cURL

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.

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

Example

cURL

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

Deleting credentials that are attached to an active trunk will break authentication for that trunk.

Example

cURL

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

cURL

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/

Trunks - Create and manage SIP trunks
IP Access Control Lists - Alternative authentication via IP whitelisting

​API Endpoint

​The Credentials Object

​Attributes

​Example Object

​List All Credentials

​HTTP Request

​Query Parameters

​Response

​Example

​Retrieve Credentials

​HTTP Request

​Response

​Example

​Create Credentials

​HTTP Request

​Request Parameters

​Response

​Error Codes

​Example

​Update Credentials

​HTTP Request

​Request Parameters

​Response

​Example

​Delete Credentials

​HTTP Request

​Response

​Example

​Usage with Trunks

​Example

​Related

API Endpoint

The Credentials Object

Attributes

Example Object

List All Credentials

HTTP Request

Query Parameters

Response

Example

Retrieve Credentials

HTTP Request

Response

Example

Create Credentials

HTTP Request

Request Parameters

Response

Error Codes

Example

Update Credentials

HTTP Request

Request Parameters

Response

Example

Delete Credentials

HTTP Request

Response

Example

Usage with Trunks

Example

Related