Provision a SIP client with the IllyVoIP SIP API

An authorized backend can use IllyVoIP’s SIP API to select a calling identity and obtain its connection settings. The bootstrap response includes a SIP password scoped to the account’s current API key. It is separate from the SIP-line password managed independently in the Portal.

Use this workflow when provisioning a compatible SIP client under your application’s control. You need an eligible identity, server-side API access and a secure way to deliver credentials to the intended client. For a browser application, prefer the Webphone SDK’s short-lived browser-token workflow instead of exposing an account API key or long-lived password.

1. List the identities your application may use

curl --silent --show-error --fail-with-body \
  'https://api.illyvoip.com/api/v1/sip/identities' \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set the server-side key}" \
  > identities.json

Inspect the returned identities, connection mode and available actions. Select the SIP identity associated with the authenticated user in your own application. Do not accept an arbitrary browser-supplied identity and pass it through with the account key.

Inactive, archived, IP-authenticated, conflicted or otherwise policy-ineligible identities cannot use this bootstrap workflow. An identity appearing in a list is not a promise that every provisioning operation is available. If the line uses IP authentication, follow that connection mode’s setup guide rather than changing its mode merely to make this request pass.

2. Request bootstrap data from your backend

Choose the supported region and SIP identity deliberately. The following request keeps the API key in a header; never place it in a public URL. Response files contain secrets and must not be published or attached to ordinary support tickets.

umask 077
curl --silent --show-error --fail-with-body --get \
  'https://api.illyvoip.com/api/v1/sip/bootstrap' \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set the server-side key}" \
  --data-urlencode "sip_user_id=${SIP_USER_ID:?Set the authorized identity}" \
  --data-urlencode "region=${REGION:?Set a supported region}" \
  > sip-bootstrap.private.json

Check the HTTP status and JSON status before configuring the client. Confirm active_sip_user_id is the selected identity. Treat the password, temporary TURN credentials and any token-like values as secrets. Use a protected secret store or client provisioning channel rather than copying the whole response into application logs.

3. Map the returned fields to your client

Use credentials.sip_user_id as the selected SIP identity and credentials.sip_password as its API-derived password. Use the applicable returned domain, proxy, transport and realm settings. A client may label these fields Username, Authentication ID, Registrar, Domain or Outbound proxy; consult its own documentation instead of assuming labels are interchangeable.

The response distinguishes general config, browser WebRTC settings and secure native settings. Select the profile your client actually supports. For an encrypted native client, follow the returned secure-native transport and media requirements together, including any documented registration contact parameter. TLS signaling alone does not establish that audio encryption is configured correctly.

Do not reuse a TURN password as a SIP password, use a WSS URL in a UDP proxy field, or silently downgrade encryption to obtain registration. Returned available regions and settings are more reliable than hardcoded infrastructure examples.

4. Confirm registration, then the intended calling workflow

First verify that the client reports registration for the expected identity. Registration does not prove incoming number routing, an approved outgoing caller ID, microphone access or two-way audio. Follow the client’s normal controlled calling checks only when authorized; they may incur charges.

For incoming calls, separately confirm that the IllyVoIP number or queue points to this identity. For outgoing calls, check account readiness and the permitted destination. Preserve the selected region, client version, time and sanitized error if a check fails; omit passwords and unnecessary telephone numbers.

5. Plan credential renewal and revocation

Rotating or disabling the account API key revokes credentials derived from that key. Include these SIP clients in your API-key cutover inventory. Update the backend’s key, obtain fresh bootstrap credentials for the same authorized identity and distribute them securely before deliberately restoring registration.

This does not require changing the independently managed SIP-line password. Do not restore the old API key or repeatedly rotate keys while a client still uses stale provisioning data. Temporary connection credentials in a bootstrap response also have their own lifetime; do not treat a saved response as permanent configuration for every future session.

Troubleshooting and limits

Bootstrap rejected: inspect the returned eligibility or authentication error before retrying. Registration fails: verify the identity, current derived password, region, transport and realm as one configuration. Registration works but calls fail: investigate routing and call permissions separately. Only one client fails after rotation: check whether it actually loaded the new credentials.

This guide explains IllyVoIP’s provisioning contract, not certification of every desk phone, PBX or mobile SIP library. Keep one documented configuration per supported client and test its behavior before deploying broadly.

Related guides and reference

• How to create SIP & Agents accounts
• Add browser calling with the Webphone SDK
• Rotate an IllyVoIP API key without losing track of integrations
• SIP bootstrap reference

Reviewed 10 October 2026 against the current IllyVoIP reference and implementation. SDK examples target version 1.4.2 where applicable. Local example checks do not certify a completed live call, routing change or third-party integration.