IllyVoIPdevelopers

SIP & browser tokens

Get SIP bootstrap data

Returns SIP registration, websocket, STUN, and provisioning details for one active password identity.

Try in API Playground ↗Sign in to prepare and run this request.
GET/api/v1/sip/bootstrap

Before you start

Select an identity you own and a supported setup mode.

Result

Use the returned SIP connection settings only for that identity and client.

Charges and safe retries

Treat returned passwords and connection credentials as secrets. For browser apps prefer temporary tokens.

Authentication

Send your account API key in the X-Api-Key header. Keep it on your server; never embed it in browser code.

Request examples

Replace the example values with your own inputs. Examples do not run on this page. Production requests can change your account or incur charges.

cURL

cURL
curl -X GET "https://api.illyvoip.com/api/v1/sip/bootstrap" \
  -H "X-Api-Key: ${ILLYVOIP_API_KEY:?Set ILLYVOIP_API_KEY}"

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/sip/bootstrap", {
  method: "GET",
  headers: {
    "X-Api-Key": process.env.ILLYVOIP_API_KEY
  }
});

const data = await response.json();
console.log(response.status, data);

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/sip/bootstrap');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-Api-Key: ' . getenv('ILLYVOIP_API_KEY')
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL;
echo $response;

Python

Python
import os
import json
import requests

response = requests.request(
    "GET",
    "https://api.illyvoip.com/api/v1/sip/bootstrap",
    headers={
        "X-Api-Key": os.environ["ILLYVOIP_API_KEY"]
    },
)

print(response.status_code)
print(response.json())

Node.js examples run on the server (Node.js 22.17+). Python examples require requests; PHP examples require cURL. Set the environment variables referenced in each example.

Request parameters

Query parameters

sip_user_idstringoptional

Optional active identity whose available_actions includes password_bootstrap.

minLength 1maxLength 64pattern "^[A-Za-z0-9_.-]{1,64}$"
regionstringoptional

Optional POP / region code such as de, us, or sg for browser WSS selection.

hostnamestringoptional

Optional explicit SIP/WSS hostname override when a region has multiple POPs.

Request behavior

Use this from a trusted backend to bootstrap a webphone, mobile client, or external SIP endpoint. The returned SIP password is scoped to the current account API key: rotating or disabling that key revokes this credential without changing the independently managed SIP-line password. Inactive, archived, IP-auth, conflicted, and policy-ineligible identities are rejected.

Response fields

  • status: Request outcome. Read the resource state separately; success does not always mean delivery or completion.
  • active_sip_user_id: Identity currently selected for this connection.
  • credentials: Connection credentials. Do not log or expose them to other users.
  • sip_users: Accessible SIP identities for selection.
  • selected_pop: Selected public connection region.
  • available_pops: Available public connection regions.
  • browser_webrtc: Browser media and connection configuration.
  • config: SIP client connection and transport settings for this identity.
  • secure_native: Connection settings for a compatible encrypted native SIP client.

HTTP responses

Expand a status to inspect its documented response format and examples. Example prices, IDs and timestamps are illustrative values, not quotes or account records.

200 Successful customer-facing response.

application/json

JSON
{
  "status": "success",
  "active_sip_user_id": "1051",
  "credentials": {
    "sip_user_id": "1051",
    "display_name": "Main account",
    "caller_id": "12494251304",
    "sip_password": "YOUR_API_SCOPED_SIP_PASSWORD"
  },
  "sip_users": [
    {
      "sip_user_id": "1051",
      "display_name": "Main account",
      "is_main": true
    }
  ],
  "selected_pop": {
    "region_code": "de",
    "hostname": "sip-de.illyvoip.com"
  },
  "available_pops": [
    {
      "region_code": "de",
      "hostname": "sip-de.illyvoip.com",
      "secure_hostname": "sip-de.illyvoip.com"
    }
  ],
  "browser_webrtc": {
    "sip_domain": "sip-de.illyvoip.com",
    "ws_server": "wss://sip-de.illyvoip.com",
    "transport": "wss",
    "webrtc": true,
    "auth_mode": "sip_password",
    "token_header_name": "X-Illy-Browser-Token",
    "transport_keepalive_seconds": 0,
    "transport_keepalive_debounce_seconds": 0,
    "options_ping_interval_seconds": 15,
    "ice_servers": [
      {
        "urls": [
          "turn:sip-de.illyvoip.com:3478"
        ],
        "username": "TEMPORARY_TURN_USERNAME",
        "credential": "TEMPORARY_TURN_CREDENTIAL"
      }
    ],
    "turn_username": "TEMPORARY_TURN_USERNAME",
    "turn_credential": "TEMPORARY_TURN_CREDENTIAL",
    "turn_expires_at": "2026-09-07T12:15:00+00:00",
    "region_code": "de",
    "media_mode": "dtls",
    "media_encryption": "dtls-srtp",
    "srtp_keying": "dtls-srtp",
    "dtls_required": true,
    "rtcp_mux_required": true
  },
  "config": {
    "sip_domain": "sip-de.illyvoip.com",
    "sip_proxy": "sip:sip-de.illyvoip.com:5060",
    "ws_server": "wss://sip-de.illyvoip.com",
    "sips": false
  },
  "secure_native": {
    "sip_domain": "sip-de.illyvoip.com",
    "sip_proxy": "sips:sip-de.illyvoip.com:5061",
    "transport": "tls",
    "realm": "sip.illyvoip.com",
    "region_code": "de",
    "registration_contact_param": "x-illy-media-mode",
    "registration_contact_value": "sdes",
    "registration_contact_uri_parameter": "x-illy-media-mode=sdes",
    "supported_media_modes": [
      "plain",
      "sdes",
      "dtls"
    ],
    "media_mode": "sdes",
    "media_encryption": "sdes-srtp",
    "srtp_keying": "sdes-srtp",
    "dtls_required": false,
    "rtcp_mux_required": false
  }
}
statusstringrequired
enum ["success"]
active_sip_user_idstringrequired
credentialsobjectrequired
View nested fields
sip_user_idstringrequired
display_namestringrequired
caller_idstringrequired
nullable true
sip_passwordstringrequired

Additional properties: not allowed.

sip_usersarray<object>required
View nested fields

Array items

sip_user_idstringrequired
display_namestringrequired
is_mainbooleanrequired

Additional properties: not allowed.

selected_popobjectrequired
View nested fields
region_codestringrequired
hostnamestringrequired

Additional properties: not allowed.

available_popsarray<object>required
View nested fields

Array items

region_codestringrequired
hostnamestringrequired
secure_hostnamestringrequired

Additional properties: not allowed.

browser_webrtcobjectrequired
View nested fields
sip_domainstringrequired
ws_serverstringrequired
transportstringrequired
webrtcbooleanrequired
auth_modestringrequired

Current customer-selected SIP registration method.

token_header_namestringrequired
transport_keepalive_secondsintegerrequired
transport_keepalive_debounce_secondsintegerrequired
options_ping_interval_secondsintegerrequired
ice_serversarray<object>required
View nested fields

Array items

urlsvaluerequired
View nested fields

oneOf schema alternatives

Type: string

Array items

Type: string

usernamestringoptional
credentialstringoptional

Additional properties: not allowed.

turn_usernamestringrequired
turn_credentialstringrequired
turn_expires_atstringrequired
region_codestringrequired
media_modestringrequired
media_encryptionstringrequired
srtp_keyingstringrequired
dtls_requiredbooleanrequired
rtcp_mux_requiredbooleanrequired

Additional properties: not allowed.

configobjectrequired
View nested fields
sip_domainstringrequired
sip_proxystringrequired
ws_serverstringrequired
sipsbooleanrequired

Additional properties: not allowed.

secure_nativeobjectrequired
View nested fields
sip_domainstringrequired
sip_proxystringrequired
transportstringrequired
realmstringrequired
region_codestringrequired
registration_contact_paramstringrequired
registration_contact_valuestringrequired
registration_contact_uri_parameterstringrequired
supported_media_modesarray<string>required
View nested fields

Array items

Type: string

media_modestringrequired
media_encryptionstringrequired
srtp_keyingstringrequired
dtls_requiredbooleanrequired
rtcp_mux_requiredbooleanrequired

Additional properties: not allowed.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "success"
      ]
    },
    "active_sip_user_id": {
      "type": "string"
    },
    "credentials": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "sip_user_id": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        },
        "caller_id": {
          "type": "string",
          "nullable": true
        },
        "sip_password": {
          "type": "string"
        }
      },
      "required": [
        "sip_user_id",
        "display_name",
        "caller_id",
        "sip_password"
      ]
    },
    "sip_users": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "sip_user_id": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "is_main": {
            "type": "boolean"
          }
        },
        "required": [
          "sip_user_id",
          "display_name",
          "is_main"
        ]
      }
    },
    "selected_pop": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "region_code": {
          "type": "string"
        },
        "hostname": {
          "type": "string"
        }
      },
      "required": [
        "region_code",
        "hostname"
      ]
    },
    "available_pops": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "region_code": {
            "type": "string"
          },
          "hostname": {
            "type": "string"
          },
          "secure_hostname": {
            "type": "string"
          }
        },
        "required": [
          "region_code",
          "hostname",
          "secure_hostname"
        ]
      }
    },
    "browser_webrtc": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "sip_domain": {
          "type": "string"
        },
        "ws_server": {
          "type": "string"
        },
        "transport": {
          "type": "string"
        },
        "webrtc": {
          "type": "boolean"
        },
        "auth_mode": {
          "type": "string",
          "description": "Current customer-selected SIP registration method."
        },
        "token_header_name": {
          "type": "string"
        },
        "transport_keepalive_seconds": {
          "type": "integer"
        },
        "transport_keepalive_debounce_seconds": {
          "type": "integer"
        },
        "options_ping_interval_seconds": {
          "type": "integer"
        },
        "ice_servers": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "urls": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                ]
              },
              "username": {
                "type": "string"
              },
              "credential": {
                "type": "string"
              }
            },
            "required": [
              "urls"
            ]
          }
        },
        "turn_username": {
          "type": "string"
        },
        "turn_credential": {
          "type": "string"
        },
        "turn_expires_at": {
          "type": "string"
        },
        "region_code": {
          "type": "string"
        },
        "media_mode": {
          "type": "string"
        },
        "media_encryption": {
          "type": "string"
        },
        "srtp_keying": {
          "type": "string"
        },
        "dtls_required": {
          "type": "boolean"
        },
        "rtcp_mux_required": {
          "type": "boolean"
        }
      },
      "required": [
        "sip_domain",
        "ws_server",
        "transport",
        "webrtc",
        "auth_mode",
        "token_header_name",
        "transport_keepalive_seconds",
        "transport_keepalive_debounce_seconds",
        "options_ping_interval_seconds",
        "ice_servers",
        "turn_username",
        "turn_credential",
        "turn_expires_at",
        "region_code",
        "media_mode",
        "media_encryption",
        "srtp_keying",
        "dtls_required",
        "rtcp_mux_required"
      ]
    },
    "config": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "sip_domain": {
          "type": "string"
        },
        "sip_proxy": {
          "type": "string"
        },
        "ws_server": {
          "type": "string"
        },
        "sips": {
          "type": "boolean"
        }
      },
      "required": [
        "sip_domain",
        "sip_proxy",
        "ws_server",
        "sips"
      ]
    },
    "secure_native": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "sip_domain": {
          "type": "string"
        },
        "sip_proxy": {
          "type": "string"
        },
        "transport": {
          "type": "string"
        },
        "realm": {
          "type": "string"
        },
        "region_code": {
          "type": "string"
        },
        "registration_contact_param": {
          "type": "string"
        },
        "registration_contact_value": {
          "type": "string"
        },
        "registration_contact_uri_parameter": {
          "type": "string"
        },
        "supported_media_modes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "media_mode": {
          "type": "string"
        },
        "media_encryption": {
          "type": "string"
        },
        "srtp_keying": {
          "type": "string"
        },
        "dtls_required": {
          "type": "boolean"
        },
        "rtcp_mux_required": {
          "type": "boolean"
        }
      },
      "required": [
        "sip_domain",
        "sip_proxy",
        "transport",
        "realm",
        "region_code",
        "registration_contact_param",
        "registration_contact_value",
        "registration_contact_uri_parameter",
        "supported_media_modes",
        "media_mode",
        "media_encryption",
        "srtp_keying",
        "dtls_required",
        "rtcp_mux_required"
      ]
    }
  },
  "required": [
    "status",
    "active_sip_user_id",
    "credentials",
    "sip_users",
    "selected_pop",
    "available_pops",
    "browser_webrtc",
    "config",
    "secure_native"
  ]
}
400 The selector is invalid, unowned, inactive, IP-authenticated, conflicted or otherwise ineligible for password bootstrap.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
401 The API key is missing or invalid.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
403 Only an authenticated account owner with enabled API access may issue an API-scoped SIP credential.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
409 The selected SIP identity or API credential generation changed during bootstrap.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
429 The API request rate limit was exceeded.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
500 An unexpected backend error occurred and an incident code was returned.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}
503 SIP connection setup is temporarily unavailable. Retry later; contact support if it persists.

application/json

statusstringrequired
enum ["error"]
messagestringrequired
error_codestringoptional

Public incident or validation code when the endpoint provides one.

nullable true
fieldsobjectoptional

Public validation details when supplied by the endpoint.

Additional properties: not allowed.

Full schema
Schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "status",
    "message"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "error"
      ]
    },
    "message": {
      "type": "string"
    },
    "error_code": {
      "type": "string",
      "nullable": true,
      "description": "Public incident or validation code when the endpoint provides one."
    },
    "fields": {
      "type": "object",
      "additionalProperties": true,
      "description": "Public validation details when supplied by the endpoint."
    }
  }
}

Sandbox scenarios

Use https://sandbox-api.illyvoip.com with Sandbox credentials and the X-Illyvoip-Sandbox-Scenario header. Omit the header for the documented success default. This header belongs to sandbox requests.

success, not-found, rate-limited, forbidden, service-unavailable

Try this operation in Sandbox · Environment setup and limitations

List SIP identitiesCreate browser tokenGet browser bootstrap from token

Search API operations, parameters, SDK and webhooks.