Skip to main content
Telepath

POST Rotate SIP Password

Rotate the SIP password for a trunk.

endpoint 
POST https://api.telepathvoice.com/v1/trunks/{id}/rotate-password

Overview

Rotate the SIP password for a trunk. Telepath generates a new cryptographically secure password and immediately invalidates the old one. The SIP username remains unchanged.

Warning: Rotating the password will immediately invalidate the old password. Update your carrier configuration with the new password before rotating to avoid service interruption.

Request

Path Parameters

id string required The unique trunk identifier (e.g., conn_abc123xyz).

This endpoint requires no request body.

Example Request

bash 
curl -X POST https://api.telepathvoice.com/v1/trunks/conn_abc123xyz/rotate-password \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json"

Python Example

python 
import requests

API_KEY = "sk_live_abc123def456..."
BASE_URL = "https://api.telepathvoice.com/v1"
TRUNK_ID = "conn_abc123xyz"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/trunks/{TRUNK_ID}/rotate-password",
    headers=headers
)
response.raise_for_status()
result = response.json()

print(f"Password rotated at: {result['rotated_at']}")
print(f"New SIP password:    {result['sip_password']}")
# Store the new password securely immediately

Response

Response Fields

id string Trunk identifier.
sip_username string SIP username — unchanged by rotation.
sip_password string The newly generated SIP password. This is the only time it is returned in plaintext — store it immediately.
rotated_at string ISO 8601 timestamp of when the rotation occurred.

Example Response

json 
{
  "id": "conn_abc123xyz",
  "sip_username": "agent-prod-01",
  "sip_password": "nEwP@ssw0rd!xYz9",
  "rotated_at": "2024-03-10T16:00:00Z"
}

Error Responses

Trunk Not Found (404)

json 
{
  "error": {
    "code": "not_found",
    "message": "Trunk 'conn_abc123xyz' not found",
    "status": 404
  }
}

Best Practices

Before Rotating

  • Confirm you have access to update your SIP carrier configuration.
  • Choose a low-traffic window to minimise call disruption.
  • Have your secrets manager ready to store the new password immediately after rotation.

Rotation Process

  1. Call this endpoint to generate the new password.
  2. Copy the sip_password from the response immediately and store it securely.
  3. Log into your SIP carrier portal and update the SIP credentials for this trunk.
  4. Verify new calls are authenticating correctly using the Dashboard or a test call.
  5. Confirm the old password is no longer accepted (it should fail with a 407 from the carrier).

After Rotating

  • The old password is immediately invalidated — any in-progress calls will complete, but new registrations using the old password will fail.
  • The new password is active from the moment the response is returned.
  • Monitor the Dashboard for authentication errors in the minutes following rotation.

Usage Examples

Safe Rotation with Verification

python 
import requests
import boto3  # AWS Secrets Manager example

def rotate_trunk_password(api_key, trunk_id, secret_name):
    """Rotate SIP password and store the result in AWS Secrets Manager."""
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    # 1. Rotate
    r = requests.post(
        f"https://api.telepathvoice.com/v1/trunks/{trunk_id}/rotate-password",
        headers=headers
    )
    r.raise_for_status()
    result = r.json()

    # 2. Store new password securely
    sm = boto3.client("secretsmanager")
    sm.put_secret_value(
        SecretId=secret_name,
        SecretString=result["sip_password"]
    )

    print(f"Rotated at {result['rotated_at']}. Secret stored in {secret_name}.")
    return result

Scheduled Rotation

python 
import schedule
import time
import requests

API_KEY = "sk_live_abc123def456..."
TRUNK_ID = "conn_abc123xyz"

def rotate_password():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    r = requests.post(
        f"https://api.telepathvoice.com/v1/trunks/{TRUNK_ID}/rotate-password",
        headers=headers
    )
    if r.ok:
        result = r.json()
        # Update your carrier configuration here...
        print(f"[{result['rotated_at']}] Password rotated successfully.")
    else:
        print(f"Rotation failed: {r.status_code} {r.text}")

# Rotate every 30 days
schedule.every(30).days.do(rotate_password)

while True:
    schedule.run_pending()
    time.sleep(3600)

See Also