Contents

PrevNext

Appendix B. Licensing API Reference developer

Abstract

For developers of software and services that check licenses: how to authenticate, the four endpoints, and every refusal.

The licensing API is part of Joomla's Web Services, added by the Web Services - PaddleSubs plugin. Every endpoint is under https://www.example.com/api/index.php/v1/paddlesubs/, answers in JSON:API (application/vnd.api+json), and includes meta.account_url: the address of the customer's My Licenses page, so your software can send the customer there.

Your software is responsible for checking that the customer controls the site it activates, for example because the software runs on that site and the customer signed in from it. PaddleSubs trusts what an authenticated client tells it.

Tokens, Service Users and Permissions

The API uses Joomla API tokens. Create a user for your software, not a person's account:

Procedure B.1. Set up a service user

  1. Create a user group, such as License API, and a user in it, such as license-service.

  2. In System → Global Configuration → Permissions, allow the group Web Services Login.

  3. In PaddleSubs' Options, on the Permissions tab, allow the group what the software needs: Read licenses (API) to list licenses and check activations, Activate sites (API) to bind sites, and Release sites (API) to release them.

  4. Make sure the plugins API Authentication - Web Services Joomla Token and User - Joomla API Token are enabled, and add the group to the latter's Allowed User Groups.

  5. Edit the user, open the Joomla API Token tab, and copy the token. Keep it secret, on your server only.

Send the token with every request:

X-Joomla-Token: token

A request without a valid token, or from a user without the permission, is answered 401 or 403. Every activation and release the API makes is recorded in the license's history as made by the API, with the service user.

On this page