IllyVoIPdevelopers

SIP & browser tokens

Get browser bootstrap from token

Returns browser SIP/WSS/TURN bootstrap using a short-lived browser token.

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

Before you start

Use the short-lived Bearer token created by your server. This endpoint does not use X-Api-Key.

Result

Apply the returned browser connection configuration before registering the client.

Charges and safe retries

Refresh expired tokens through your trusted server; never log tokens or credentials.

Authentication

Use the short-lived browser token in the Authorization: Bearer header. This operation does not use the permanent account API key.

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/browser-bootstrap" \
  -H "Authorization: Bearer YOUR_BROWSER_TOKEN"

Node.js

Node.js
const response = await fetch("https://api.illyvoip.com/api/v1/sip/browser-bootstrap", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_BROWSER_TOKEN"
  }
});

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

PHP

PHP
<?php
$ch = curl_init('https://api.illyvoip.com/api/v1/sip/browser-bootstrap');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_BROWSER_TOKEN'
    ],
]);

$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/browser-bootstrap",
    headers={
        "Authorization": "Bearer YOUR_BROWSER_TOKEN"
    },
)

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 behavior

This is the managed SDK bootstrap endpoint. Send Authorization: Bearer <token> from your frontend after your backend has minted the token.

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.
  • auth: Authentication settings for the selected connection; handle credentials as secrets.
  • browser_auth: Temporary browser authentication settings.

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_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": "browser_token",
    "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
  },
  "auth": {
    "mode": "browser_token",
    "expires_at": "2026-09-07T12:15:00+00:00"
  },
  "browser_auth": {
    "mode": "token",
    "header_name": "X-Illy-Browser-Token",
    "scope": "sip_browser_session",
    "expires_at": "2026-09-07T12:15:00+00:00"
  }
}
statusstringrequired
enum ["success"]
active_sip_user_idstringrequired
credentialsobjectrequired
View nested fields
sip_user_idstringrequired
display_namestringrequired
caller_idstringrequired
nullable true

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.

authobjectrequired
View nested fields
modestringrequired
expires_atstringrequired

Additional properties: not allowed.

browser_authobjectrequired
View nested fields
modestringrequired
header_namestringrequired
scopestringrequired
expires_atstringrequired

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
        }
      },
      "required": [
        "sip_user_id",
        "display_name",
        "caller_id"
      ]
    },
    "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"
      ]
    },
    "auth": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "mode": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        }
      },
      "required": [
        "mode",
        "expires_at"
      ]
    },
    "browser_auth": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "mode": {
          "type": "string"
        },
        "header_name": {
          "type": "string"
        },
        "scope": {
          "type": "string"
        },
        "expires_at": {
          "type": "string"
        }
      },
      "required": [
        "mode",
        "header_name",
        "scope",
        "expires_at"
      ]
    }
  },
  "required": [
    "status",
    "active_sip_user_id",
    "credentials",
    "sip_users",
    "selected_pop",
    "available_pops",
    "browser_webrtc",
    "auth",
    "browser_auth"
  ]
}
400 An unsupported query parameter was supplied.

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 browser token is missing, invalid or expired.

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 token identity ownership or browser lease is no longer valid.

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 identitiesGet SIP bootstrap dataCreate browser token

Search API operations, parameters, SDK and webhooks.