# Issue a new digest password — shown once

Source: https://docs.usetone.ai/reference/sip-trunks/rotate

> 🔴 The previous password stops working within seconds.

`POST /v1/sip-trunks/{id}/credentials/rotate`
🔴 The previous password stops working within seconds. Update your PBX first if it registers, then rotate. The new password appears in this response only.

Requires the `admin` scope.

## Parameters

| Name | In | | Meaning |
|---|---|---|---|
| `id` | path | required | The SIP trunk's id. |

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `connection` | object | required | Everything your PBX needs to register or send INVITEs. The password appears in this response only. |
| `connection.host` | string | required | What to point your PBX at. |
| `connection.ips` | string[] | required | The gateway's public addresses, for your firewall. |
| `connection.password` | string | required | Shown exactly once — now. Store it. Rotating issues a new one and invalidates this. |
| `connection.port` | integer | required | Signalling port. |
| `connection.realm` | string | required | The digest realm. |
| `connection.transport` | string | required | Signalling transport. |
| `connection.username` | string | required | The digest username your PBX authenticates with. |
| `trunk` | object | required | The trunk, as it now stands. |
| `trunk.allowOrigination` | boolean | required | Whether this trunk may ORIGINATE: send Tone an INVITE for a number Tone does not host and have Tone dial it out. Granted by Tone support, not settable here. Every originated call runs the full pre-dial compliance gate before anything is dialled. |
| `trunk.approvedAt` | string | null | required | When our team approved the trunk. Null while pending. |
| `trunk.callerIdPolicy` | string | required | Which number outbound INVITEs present as From. Open set — handle an unrecognised value rather than throwing. Today: `did`, `trunk_default`. |
| `trunk.codecs` | string[] | required | Codec preference order, best first. |
| `trunk.connection` | object | required | Where your PBX sends INVITEs. The same for every trunk on this deployment. |
| `trunk.connection.host` | string | required | What to point your PBX or SBC at. |
| `trunk.connection.ips` | string[] | required | The gateway's public addresses, for your firewall allow-list. Signalling and media both originate here. |
| `trunk.connection.port` | integer | required | Signalling port. TLS. |
| `trunk.connection.transport` | string | required | Signalling transport Tone accepts. |
| `trunk.createdAt` | string | required | RFC 3339, UTC. |
| `trunk.customHeaders` | object | required | Extra X-* headers on every outbound INVITE. |
| `trunk.digestUsername` | string | null | required | The username your PBX authenticates with. 🔴 Its password is returned exactly once, at creation and at rotation, and never again. |
| `trunk.disabledReason` | string | null | required | Why the trunk is disabled, when it is. |
| `trunk.hasOutboundPassword` | boolean | required | Whether an outbound password is stored. The value itself is never returned. |
| `trunk.id` | string | required | The trunk's id. |
| `trunk.inboundAuth` | string | required | How the gateway authenticates INVITEs from your PBX. Open set — handle an unrecognised value rather than throwing. Today: `ip_acl`, `digest`, `both`. |
| `trunk.ipAcl` | string[] | required | Public CIDRs your SBC sends from, canonicalised. |
| `trunk.lastInboundAt` | string | null | required | When a call last arrived over this trunk. RFC 3339, UTC. |
| `trunk.lastOutboundAt` | string | null | required | When Tone last placed a call over this trunk. RFC 3339, UTC. |
| `trunk.lastProbe` | object | null | required | The most recent POST /v1/sip-trunks/{id}/test result, or null if never tested. |
| `trunk.maxConcurrent` | integer | required | Concurrent calls this trunk may carry, both directions combined. |
| `trunk.name` | string | required | Your own name for it. |
| `trunk.outboundAuthUsername` | string | null | required | Username Tone presents to your carrier. |
| `trunk.outboundHost` | string | null | required | Where Tone sends outbound INVITEs. |
| `trunk.outboundNumberFormat` | string | required | Dialled-number format toward your carrier. Open set — handle an unrecognised value rather than throwing. Today: `e164`, `national`, `national0`. |
| `trunk.outboundPort` | integer | required | Port on outboundHost. |
| `trunk.outboundTransport` | string | required | Transport toward your carrier. Open set — handle an unrecognised value rather than throwing. Today: `tls`, `tcp`, `udp`. |
| `trunk.realm` | string | required | The digest realm the gateway challenges with. |
| `trunk.register` | boolean | required | Whether Tone REGISTERs to your carrier. |
| `trunk.status` | string | required | Lifecycle. `pending_verification` until our team approves the carrier relationship; only `active` carries calls; `disabled` is the kill switch and `disabledReason` says why. Open set — handle an unrecognised value rather than throwing. Today: `pending_verification`, `active`, `disabled`. |
| `trunk.updatedAt` | string | required | RFC 3339, UTC. |

### Example response

```json
{
  "data": {
    "connection": {
      "host": "sip.usetone.ai",
      "ips": [
        "13.233.10.20"
      ],
      "password": "Qm9vZ2llV29vZ2llMTIzNDU2",
      "port": 5061,
      "realm": "sip.usetone.ai",
      "transport": "tls",
      "username": "t_9f2c4a7b1d3e5f60"
    },
    "trunk": {
      "allowOrigination": false,
      "approvedAt": "2026-09-09T11:00:00Z",
      "callerIdPolicy": "did",
      "codecs": [
        "PCMA",
        "PCMU"
      ],
      "connection": {
        "host": "sip.usetone.ai",
        "ips": [
          "13.233.10.20"
        ],
        "port": 5061,
        "transport": "tls"
      },
      "createdAt": "2026-09-09T10:14:22Z",
      "customHeaders": {},
      "digestUsername": "t_9f2c4a7b1d3e5f60",
      "disabledReason": null,
      "hasOutboundPassword": true,
      "id": "4b7c1a02-9de5-4f31-bb07-2c1a5e9f0d43",
      "inboundAuth": "digest",
      "ipAcl": [
        "49.207.12.0/24"
      ],
      "lastInboundAt": "2026-09-10T08:12:44Z",
      "lastOutboundAt": null,
      "lastProbe": {
        "at": "2026-09-10T08:12:44Z",
        "error": null,
        "latencyMs": 41,
        "method": "options",
        "ok": true,
        "sipStatus": 200
      },
      "maxConcurrent": 10,
      "name": "Airtel SIP — Mumbai office",
      "outboundAuthUsername": "acme-out",
      "outboundHost": "sbc.acme-telecom.example",
      "outboundNumberFormat": "e164",
      "outboundPort": 5061,
      "outboundTransport": "tls",
      "realm": "sip.usetone.ai",
      "register": false,
      "status": "active",
      "updatedAt": "2026-09-10T08:12:44Z"
    }
  }
}
```