[Existing Endpoint Change] add `username` and `password` for Sip Authentication to REST Call Create API

[cassieemb]

references https://github.com/signalwire/cloud-product/issues/19491

Summary

The Calling API dial endpoint (POST /api/calling/calls with command: "dial") now accepts two optional request fields, username and password, for authenticating against a SIP destination. When a call is dialed to a SIP address that requires credentials, these values are forwarded to the dial engine so the outbound SIP INVITE can authenticate.

This brings the REST Calling API to parity with the LaML call-create API, which has always supported the equivalent SipAuthUsername / SipAuthPassword parameters. Previously there was no way to pass SIP auth credentials when starting a call through the REST Calling API.

Note

These fields apply only to SIP destinations (when to is a SIP URI). If the call is dialed to a PSTN number or a WebRTC/verto endpoint, username and password are ignored. They are also never returned in any API response - the password in particular is write-only.

Authentication & scope

• Auth: HTTP Basic auth using Project ID (username) + API token (password).
• Base URL: https://<your-space>.signalwire.com

Endpoints

This is a field addition to an existing endpoint, not a new endpoint.

Method	Path	Description
POST	/api/calling/calls	Start an outbound call. With command: "dial", now accepts optional username / password for SIP destination authentication.

Limitations

• username and password apply only when the destination (to) is a SIP address. They are silently ignored for PSTN and WebRTC/verto destinations.
• Both fields are optional. Pass them together when the SIP endpoint requires authentication; omit both when it does not.
• The fields are write-only: they are stored on the call leg and forwarded to the dial engine, but are never echoed back in the call-create response or any subsequent call resource.
• There are no format constraints on the values - they are accepted as free-form strings.

Fields

Writable fields (dial request body)

Field	Type	Notes
username	string	Optional. SIP auth username used to authenticate against the SIP destination. Applies only when to is a SIP address.
password	string	Optional. SIP auth password used to authenticate against the SIP destination. Applies only when to is a SIP address. Write-only; never returned in a response.

Response object

No response fields are added or changed. username / password are not included in the response body.

Request / response examples

Dial a SIP destination with auth - POST /api/calling/calls

Request

{
  "command": "dial",
  "from": "+15557654321",
  "to": "sip:alice@sip.example.com",
  "url": "https://example.com/call-handler",
  "username": "alice",
  "password": "s3cr3t"
}

Response - 200 OK

{
  "id": "b3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "from": "+15557654321",
  "to": "sip:alice@sip.example.com",
  "direction": "outbound",
  "state": "created"
}

(The response is the standard call segment representation and does not contain username or password. Example response fields shown are illustrative.)

Documentation change requested

Update the Calling API "Dial a Call" / create-call reference to document the two new optional request parameters (username, password), including:

• That they are optional and used for SIP destination authentication.
• That they only take effect for SIP (sip:) destinations and are ignored otherwise.
• That the password is write-only and never returned.

No new error codes are introduced.

OpenAPI Spec (request body additions)

openapi: 3.0.3
info:
  title: Calling API - Dial a Call (SIP auth fields)
  version: "1.0.0"
paths:
  /api/calling/calls:
    post:
      summary: Start an outbound call
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                command:
                  type: string
                  example: dial
                from:
                  type: string
                  example: "+15557654321"
                to:
                  type: string
                  description: Destination. May be a phone number or a SIP URI.
                  example: "sip:alice@sip.example.com"
                username:
                  type: string
                  description: >
                    Optional SIP auth username used to authenticate against the SIP
                    destination. Applies only when `to` is a SIP address; ignored for
                    PSTN and WebRTC destinations. Write-only; never returned in responses.
                  example: alice
                password:
                  type: string
                  description: >
                    Optional SIP auth password used to authenticate against the SIP
                    destination. Applies only when `to` is a SIP address; ignored for
                    PSTN and WebRTC destinations. Write-only; never returned in responses.
                  example: s3cr3t