External Provisioning

External provisioning is an optional extension to Cloud Softphone’s standard provisioning workflow. It allows providers to apply dynamic logic at the moment the app signs in or activates, making it possible to integrate with backend systems, enforce business rules, and supply configuration or credentials that depend on the individual user. This adds a flexible, real-time layer on top of the static provisioning defined in the Cloud Softphone portal.

External provisioning is commonly used for:

  • Access control and session management.

  • Issuing user-specific SIP credentials.

  • Returning per-user configuration overrides.

  • Creating new users during onboarding.

From a technical perspective, the external provisioning endpoint is invoked after the app downloads its base provisioning from the Cloud Softphone portal. The app sends a set of input parameters, including username and password, to the provider’s web service. The service returns an Account XML document, which is merged with the default provisioning to produce the final configuration used by the app.

Web Service Definition

External provisioning consists of two related but separately configurable web services:

    1. Initial external provisioning, triggered when the user signs in or activates the app for the first time

    1. Re-provisioning, triggered automatically on app startup and periodically if enabled

Both web services are configured in the Cloud Softphone portal and follow the standard Web Service Definition syntax, but each uses its own prefix and placeholder rules.

Initial External Provisioning

Initial external provisioning uses the prefix InitialProvisioning, for example:

  • InitialProvisioningUrl

  • InitialProvisioningPostData

  • InitialProvisioningMethod

At this stage, the app has not yet created an account, so the web service receives parameters directly from the initial login screen. The following placeholders are available:

  • %username% — the username entered by the user

  • %password% — the password entered by the user

  • %fullcode% — the Cloud ID of the application

These placeholders are expanded directly in the URL or request body before the web service is called.

Account XML does not yet exist at this stage; %account[...]% cannot be used during initial provisioning. The %username% and %password% values come directly from the login screen.

Re-Provisioning

Re-provisioning uses the prefix extProv:

  • extProvUrl - the URL of the re-provisioning web service

  • extProvMethod - the HTTP method to use for the re-provisioning web service

  • extProvPostData - the POST data to send to the re-provisioning web service

  • extProvInterval - the interval in seconds at which the app will automatically call the re-provisioning web service

  • extProvLogoutStatusCode - the HTTP status code to return to trigger logout

Unlike initial provisioning, re-provisioning operates on an existing account. Because of this, the service must use the %account[...]% placeholder syntax to access values stored in the Account XML, such as:

  • %account[username]%

  • %account[password]%

  • %account[X-install-id]%

The initial placeholders %username% and %password% do not work during re-provisioning and must be wrapped in account[...].

Warning

During re‑provisioning, %username% and %password% DO NOT expand. They must be referenced as %account[username]% and %account[password]%.

Re‑provisioning executes on application startup and, if enabled via extProvInterval, the app will periodically re-call the re-provisioning web service using the extProv* parameters.

  • The app sends If-Modified-Since header, allowing the provider to return 304 Not Modified.

  • If 200 OK is returned with updated Account XML, the app merges the changes and refreshes the account.

Warning

The default value for extProvInterval is 0, which means that external re-provisioning will be called only when creating or editing account. To enable periodical automatic re-provisioning, specify non-zero value of extProvInterval in your Account XML.

Note

To avoid conflicts, the account is not modified when Settings page of the application is open, or if there is a call in progress. As soon as the user closes Settings and/or all calls end, the changes are applied.

Web Service Response

The external provisioning web service must respond with an HTTP 2xx OK status code and an XML body containing the root node:

<account> ... </account>

The Content-Type should be application/xml. The XML subtree inside the <account> node represents the Account XML and will be merged into the app’s configuration.

The XML must contain exactly one <account> root node; additional nodes or wrappers are ignored. When merging, nodes returned in the <account> XML override values from the base provisioning.

If the service returns a non-2xx status code, the provisioning process stops and the app shows a generic error message. To display a custom error message, return a non-2xx status and include:

<error>
  <message>Custom error message comes here</message>
</error>

Example of Successful External Provisioning

Request

GET /prov?cloud_username=johndow&cloud_password=12345678&cloud_id=EXAMPLE&initialScreen=1 HTTP/1.1
Host: provider.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6

Response

HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 183
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml

<account>
  <username>B63349F4EE</username>
  <password>45F4BF5F0E191F5DCC27</password>
  <allowMessage>0</allowMessage>
  <X-install-id>AD4535EF902BB13</X-install-id>
</account>

This example demonstrates initial provisioning returning dynamically assigned SIP credentials.

Use Cases for External Provisioning

External provisioning gives providers granular control over account setup and ongoing configuration. Typical use cases include:

1. Delivering SIP Credentials Without Exposing Them to the End User

Many providers authenticate users using email, phone number, customer ID, or another identifier that is not the actual SIP username. External provisioning allows:

  • The user to sign in using a simple credential

  • The provider’s backend to validate the user

  • The backend to return the real SIP username and password inside the <account> XML

This ensures each user receives the correct SIP credentials without ever seeing or learning those credentials.

2. Per-User Configuration Overrides

Providers can adjust configuration dynamically for individual users. Any parameter from Account XML can be overridden based on:

  • Service tier

  • Subscription level

  • Device type

  • Backend rules

For example, disabling messaging for a specific user:

<allowMessage>0</allowMessage>

Or enabling/disabling other features on a per-user basis.

3. Controlling Access to Features

External provisioning can be used to tailor feature availability at the user level. Examples include:

  • Linkup Messaging (<linkupMessagingEnabled>0</linkupMessagingEnabled>)

  • Conferencing (<conferencingEnabled>0</conferencingEnabled>)

  • Any provider-defined add-on service

This gives providers precise control over which capabilities are available to each user.

4. Adding Custom Account Parameters

Providers may return additional XML nodes to store metadata or internal identifiers. These values are preserved in the account and can be referenced later using:

%account[customNode]%

For example:

<X-install-id>AD4535EF902BB13</X-install-id>

This can be used for analytics, tracking, device registration, or routing logic.

5. User Onboarding and Automatic Account Creation

Initial external provisioning can serve as an integration hook for creating users in the provider’s backend. Typical flows include:

  • Creating a SIP account during activation

  • Allocating phone numbers or extensions

  • Initializing service resources for first-time users

This allows providers to offer a smooth sign-up or activation experience without requiring manual backend operations.

Note

Feature overrides returned by external provisioning (for example allowMessage or linkupMessagingEnabled) override portal defaults during merge. However, paid or licensed features must still be enabled in the Cloud Softphone portal for them to be configurable via external provisioning.

6. Enforcing Logout via External Provisioning

External provisioning can be used to enforce user logout based on a specific HTTP status code returned by the re‑provisioning web service. See enforcing-logout-via-external-provisioning for more details.

Enforcing Logout via External Provisioning

Overview

Mobile and desktop applications can enforce a user logout based on a specific HTTP status code returned by the external re‑provisioning web service. This is configured using the extProvLogoutStatusCode parameter in the Web Service Definition.

Purpose

This mechanism is helpful in scenarios such as:

  • Off‑boarding customers or employees

  • Enforcing password resets or credential rotation

  • Temporary access revocation

How to Configure

In the Cloud Softphone portal, set the parameter for re‑provisioning:

  • extProvLogoutStatusCode

Set this value to the HTTP status code your provisioning service will return to trigger logout.

For example, if extProvLogoutStatusCode = 410, returning HTTP 410 Gone from the provisioning server forces immediate logout.

Behavior on Logout

When the provisioning web service returns the configured status code:

  • The user is unregistered from SIP.

  • The application notifies the Account Removal Reporter (if configured).

  • A local encrypted backup is created, containing Preferences, local call history, and Quickdials. On the next successful login, the backup is automatically restored.