Skip to content

Extensions API

Extensions are the modules that add features to ClientFence, plus languages. These calls list the modules, turn them on and off, read and save a module’s settings, and turn languages on and off. ClientFence does not download extensions from FOSSBilling’s extension directory. See Modules for building one and Languages for the languages.

Admin calls need Module access on the Extension card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.

POST /api/admin/extension/get_list

Lists modules with their manifest details: active ones, deactivated ones and those whose files are on the server but were never activated.

Permission: View extensions (extension.view)

Parameter Type Description
installed boolean true: only active (installed) modules.
active boolean true: the core modules plus the active ones.
has_settings boolean true: only modules with a settings page.
search string Text the module’s name contains.
type string Only installed extensions of this type, such as mod.

Returns: A list (not paged) of modules. Each has the module’s manifest fields: id, type (mod), name, description, version, author, author_url, homepage_url, project_url, license, icon_url, download_url, minimum_fossbilling_version, maximum_fossbilling_version and any other field the manifest has; plus status (core, installed, or null for a module that is not active), has_settings and, when the module ships its icon, icon_path.

Rows of modules whose files were removed from the server are deleted while the list is built.

Example

Request parameters:

{
"installed": true,
"search": "redirect"
}

result:

[
{
"id": "redirect",
"type": "mod",
"name": "Redirect",
"description": "Sends visitors from old client-area paths to new pages or other sites, with a permanent (301) or temporary (302) redirect.",
"homepage_url": "https://clientfence.com/",
"author": "ClientFence",
"author_url": "https://clientfence.com/",
"license": "N/A",
"version": "2.0.0",
"icon_url": "https://billing.example.com/modules/Redirect/icon.svg",
"download_url": null,
"project_url": "https://clientfence.com/docs/extensions/redirect/",
"minimum_fossbilling_version": null,
"maximum_fossbilling_version": null,
"status": "installed",
"has_settings": true,
"icon_path": "mod_Redirect_icon.svg"
}
]

POST /api/admin/extension/get_latest

Lists the extensions available in an online extension directory. ClientFence does not use FOSSBilling’s directory, so the list is always empty.

Permission: View extensions (extension.view)

Parameter Type Description
type string An extension type to filter by. It has no effect while the list is empty.

Returns: An empty list ([]).

POST /api/admin/extension/get_extension_readme

Returns an extension’s readme from the online extension directory as HTML. ClientFence does not use that directory, so the call always fails.

Permission: View extensions (extension.view)

Parameter Type Description
extension_id string, required The extension’s ID.

Returns: The readme as HTML (not reached).

Errors:

  • Extension ID was not passed
  • The FOSSBilling extension directory is not used by ClientFence. (code 746)

POST /api/admin/extension/get_navigation

Returns the admin menu the caller sees: the groups and pages of every module the staff member may open.

Parameter Type Description
url string Accepted but not used.

Returns: An object of menu groups keyed by their position. Each group has the module’s menu fields (such as index, label, uri, class), active (false) and subpages (each with label, uri, index, class, active). Groups with no page the caller may open are left out.

Every staff account may call this, even without access to the Extensions module: it answers only for the caller.

POST /api/admin/extension/languages

Lists the languages installed on the server, turned on or turned off.

Permission: View extensions (extension.view)

Parameter Type Description
disabled boolean true for the turned-off languages. Default false (the turned-on ones).
details boolean true (default) for objects with names, false for codes only.

Returns: With details: a list of objects with locale (such as de_DE), title and name (the language’s name). Without: a list of codes.

Example

Request parameters:

{
"details": true
}

result:

[
{
"locale": "de_DE",
"title": "German (Germany)",
"name": "German (Germany)"
},
{
"locale": "en_US",
"title": "English (United States)",
"name": "English (United States)"
}
]

POST /api/admin/extension/toggle_language

Turns a language on when it is off, or off when it is on.

Permission: Manage extensions (extension.manage_extensions)

Parameter Type Description
locale_id string, required The language code, such as de_DE.

Returns: true when the language was switched.

Errors:

  • Locale ID was not passed
  • Unable to enable / disable the locale as it is not present in the locale folder.

POST /api/admin/extension/locale_completion

Returns how much of a language is translated.

Permission: View extensions (extension.view)

Parameter Type Description
locale_id string, required The language code, such as fr_FR.

Returns: A whole number from 0 to 100 (always 100 for en_US; 0 when the language is unknown).

Errors:

  • Locale ID was not passed

POST /api/admin/extension/update

Upgrades an active module whose files are newer than the version recorded: runs the module’s upgrade step and records the new version. Cron does this on its own for every active module.

Permission: Manage extensions (extension.manage_extensions)

Parameter Type Description
id string, required The module’s ID, such as redirect.
type string, required The extension type: mod.

Returns: An object: id, type and version (the new version).

Errors:

  • Extension ID was not passed
  • Extension type was not passed
  • Extension not found (it is not active)
  • Visit the extension directory for more information on updating this extension. (code 252): the files are not newer, or it is a core module.

Fires onBeforeAdminUpdateExtension and onAfterAdminUpdateExtension.

POST /api/admin/extension/activate

Activates a module whose files are on the server: runs its install step and records its version.

Permission: Manage extensions (extension.manage_extensions)

Parameter Type Description
id string, required The module’s ID, such as redirect.
type string, required The extension type, such as mod.

Returns: An object: id, type, redirect (true when the module has admin pages) and has_settings.

Errors:

  • Extension ID was not passed
  • Extension type was not passed
  • Missing manifest file for the module. (code 5897)
  • ClientFence core modules cannot be installed or removed
  • Module cannot be installed. It requires or later; this site has .

Fires onBeforeAdminActivateExtension and onAfterAdminActivateExtension, and rebuilds the widget registry. When the install step fails, nothing is recorded.

Example

Request parameters:

{
"id": "redirect",
"type": "mod"
}

result:

{
"id": "redirect",
"type": "mod",
"redirect": true,
"has_settings": true
}

POST /api/admin/extension/deactivate

Deactivates a module. Its settings and data stay; activate it again to use it.

Permission: Manage extensions (extension.manage_extensions)

Parameter Type Description
id string, required The module’s ID.
type string, required The extension type, such as mod.

Returns: true

Errors:

  • Extension not found
  • Core modules are an integral part of the ClientFence system and cannot be deactivated.
  • This module provides , which is still installed. Remove it first, then deactivate the module. (a payment gateway, registrar or server manager the module ships is still in use)

Fires onBeforeAdminDeactivateExtension and onAfterAdminDeactivateExtension, and rebuilds the widget registry.

POST /api/admin/extension/uninstall

Uninstalls a deactivated module: runs its uninstall step (which usually deletes its data) and deletes its files from the server.

Permission: Uninstall extensions (extension.uninstall_extensions)

Parameter Type Description
id string, required The extension’s ID: letters, digits, _ and -.
type string, required mod, theme, translation or payment-gateway.

Returns: true

Errors:

  • Core modules are an integral part of the ClientFence system and cannot be uninstalled.
  • Cannot uninstall an active module. Please deactivate it first.
  • Extension ID contains invalid characters.
  • An exception was thrown by the module:
  • Could not find the extension files in the supposed path. Please remove them from the disk manually.

This cannot be undone: the module’s files and, for most modules, its data are deleted. Fires onBeforeAdminUninstallExtension and onAfterAdminUninstallExtension.

POST /api/admin/extension/install

Downloads an extension from the online extension directory. ClientFence does not use that directory, so the call always fails; copy a module’s files to the server and use activate instead.

Permission: Manage extensions (extension.manage_extensions)

Parameter Type Description
id string, required The extension’s ID.
type string, required The extension type.

Returns: An object: success, id and type (not reached).

Errors:

  • The FOSSBilling extension directory is not used by ClientFence. (code 746)

POST /api/admin/extension/config_get

Returns a module’s saved settings.

Permission: Manage settings of that module (<module>.manage_settings). For a module that is not active: Manage extensions (extension.manage_extensions). Staff without access to the Extensions module may call it.

Parameter Type Description
ext string, required The module, as mod_<name> (such as mod_invoice). Anything but a string is refused with “Parameter "ext" was not passed”.

Returns: An object of the module’s settings (each module has its own keys), plus ext. For mod_email, staff who are not Super Administrators do not get smtp_password, sendgrid_key and custom_dsn.

Errors:

  • Parameter “ext” was not passed
  • Unknown extension. (code 404)
  • You do not have permission to access the : module (code 403)
  • You do not have permission to perform this action (code 403): the module has no Manage settings permission, or the caller lacks it
Example

Request parameters:

{
"ext": "mod_cron"
}

result:

{
"guest_cron": false,
"cron_hash": "",
"ext": "mod_cron"
}

POST /api/admin/extension/config_save

Saves a module’s settings. The saved settings are replaced by what you send, so read them with config_get first, change what you need and send them all back.

Permission: Manage settings of that module (<module>.manage_settings). For a module that is not active: Manage extensions (extension.manage_extensions). Staff without access to the Extensions module may call it.

Parameter Type Description
ext string, required The module, as mod_<name>.
(settings) mixed Every other key is saved as a setting of the module.

Returns: true

Errors:

  • Parameter “ext” was not passed
  • The same permission errors as config_get.

Settings that a module’s settings page saves with its own forms are kept even when you leave them out. For mod_email, staff who are not Super Administrators cannot change the sending settings (mailer, custom_dsn, smtp_host, smtp_port, smtp_username, smtp_password, sendgrid_key); those keep their saved values. Fires onBeforeAdminExtensionConfigSave and onAfterAdminExtensionConfigSave. Settings are stored encrypted.

Example

Request parameters:

{
"ext": "mod_cron",
"guest_cron": false,
"cron_hash": ""
}

result:

true

POST /api/guest/extension/is_on

Says whether a module or another extension is active.

Parameter Type Description
mod string A module’s name, such as support.
id string Another extension’s ID, used with type when mod is not given.
type string That extension’s type.

Returns: true or false. Core modules are always active. With neither mod nor id and type, true.

Example

Request parameters:

{
"mod": "redirect"
}

result:

true

POST /api/guest/extension/settings

Returns the public part of an active module’s settings (the public key), which a module may fill for its client pages.

Parameter Type Description
ext string, required The module, as mod_<name> or <name>.

Returns: The module’s public settings object, or an empty list when the module is not active or has none.

Errors:

  • Parameter ext is missing

POST /api/guest/extension/languages

Lists the codes of the languages that are turned on.

Parameter Type Description
details boolean true: each language as locale, title and name instead of the code alone.

Returns: A list of language codes, such as ["de_DE", "en_US"].