Documentation

Licensing

Any add-on intended for sale on the Atlassian Marketplace needs to be license-enabled. Add-ons collaborate with the Atlassian application to apply licensing requirements.

The Atlassian application reports the licensing status of the instance to the plugin in each request.

The add-on should:

  • check the license status in service requests it receives from the Atlassian application
  • implement the logic appropriate for the given license status. For instance, for an inactive license, the add-on may choose to disable its features, enter a read-only state, or function in some other restricted manner that makes sense

Development considerations

In a nutshell, to implement licensing for Atlassian Connect, you need to:

  • set the enableLicensing flag in the add-on descriptor for the add-on
  • write code to check the lic URL parameter for all incoming requests
  • use the Atlassian Connect REST resource /addons/{addonKey} to get additional license information for each application
  • implement the logic appropriate for the add-on based on the license status
  • use a private listing with access tokens to test all license statuses in a Cloud instance

Note:

The result of a license check by the Atlassian application is cached for 5 minutes.

Enabling add-on licensing

To implement licensing in an add-on, set the enableLicensing flag in the add-on descriptor file (atlassian-connect.json) to true. Any add-on intended for sale should have this flag enabled.

{
    "name": "Hello World",
    "key": "hello-world",
    "description": "Atlassian Connect add-on",
    "baseUrl": "http://www.example.com",
    "enableLicensing": true
}

This tells UPM to check and report licensing status to the plugin. On the other hand, if you are using a plugin strictly for internal use or you plan to distribute it freely on the Marketplace, this should be set to false.

Handling requests with the license status

Each incoming request from the Atlassian application instance includes a query parameter named lic.

http://....?lic=active

Your add-on should check this value to determine the license status of the instance associated with the current request. The lic parameter may have either of the following values:

  • active – the license is valid for this instance and add-on
  • none – no license is present

Accessing license details

In addition to the lic parameter, an add-on can use the REST API resource /addons/{addonKey} provided by Atlassian Connect to get an instance's license for this plugin. Note, you will need to declare READ scope in order to use this resource.

Testing license enforcement

You can test licensing-related behavior of your add-on in a local, development environment to an extent. But there's no way to replicate the interaction with the UPM and Atlassian Marketplace in a local environment alone. In the production environment, the Atlassian Marketplace serves licenses for new subscribers, and the application interacts with the Marketplace to get the license state.

Installing your add-on in a cloud instance using an access token allows instance administrators to modify the license status of the add-on. This enables you to ensure that your add-on functions properly in all license statuses.