If you built a Hello World app, ran Jira Cloud in development mode,
and installed your app manually into the product, then the next phase of your app development is to test
your app being installed via the Atlassian Marketplace.
This is important if you wish to test your app in a licensed state, or start along the
path to listing your app. This is necessary whether you want to eventually make your app available
privately or publicly, free or paid.
Before starting
There are a few prerequisites before you create your Marketplace listing:
Create or get access to a cloud-hosted product instance
You can create an environment for testing simply by signing up
for a free development cloud product.
Your app and your atlassian-connect.json descriptor file are served over HTTPS
Your app (and your atlassian-connect.json descriptor) must be served over HTTPS to be installed into
a cloud instance. Your app must have a baseUrl that starts with https://;
a baseUrl of the form http://my-server.example.com:443/ will not be accepted. Additionally, your HTTPS
certificate cannot be self-signed.
You have an Atlassian user account associated with the Marketplace
You need a Marketplace user account associated with a partner profile to create a listing. You can create a new
partner profile when you create your listing, or have your account added to an existing profile by somebody already
associated with it. To get an account associated with the Marketplace, sign up here.
Creating the Marketplace listing
With your Marketplace account set up and app descriptor on hand, create the Atlassian Connect
listing as follows:
Click Publish a new app from the profile menu in the upper right.
Choose a vendor.
If you don't have a vendor profile yet, click Register your organization and contact details to configure a new vendor
profile for your app.
For apps you'd like to list on the Marketplace, choose Public.
For internal-only apps, choose Private as the app visibility option.
If you intend to use the app for internal-use only, it can remain private for the lifetime of the listing.
Provide the URL to your app descriptor.
Follow the instructions to configure the remaining fields and options on the form.
Many of the fields are optional and only apply to public listings. If you're listing privately, you can leave these
for later. There are a few fields that require a little more explanation for an Atlassian Connect app listing:
Payment model: Choose only Free or Paid via Atlassian.
Atlassian Connect apps can't be listed as paid via vendor.
Availability: This field specifies the Atlassian application deployment model (Cloud or Server).
Connect apps are only available for cloud-hosted applications, so this field is
pre-populated accordingly for you.
Version visibility: While the listing has a visibility setting, so do individual versions
of your app. This lets you beta test version updates privately before publishing them. While different
versions of an app can have different visibility settings, note that if you make the listing itself
private, all versions of the apps also become private, even if they were previously published as public
versions.
Beta release: Indicates that your app version is in the testing stage only.
Choose this option if you intend to list the app publicly, but it isn't ready yet.
Compatible application: For an Atlassian Connect app, after you choose the product you
are targeting and the minimum version, the Compatible to version is uneditable (that is, it defaults to
Any). Because Atlassian Connect apps use stable, forward-compatible web APIs and cloud versions are
frequently updated, the notion of a latest-compatible version is absent for Atlassian Connect apps. It is
applicable, however, to downloadable Java apps.
Click Submit.
Now, you can generate test license tokens for your app and install it in cloud instances,
either through MyAtlassian for live instances, or through the descriptor link of the
listing view for locally-running instances. The next section provides more detail on how to do this.
Access tokens
If you created a private listing in the Marketplace, you can create and use access tokens.
Access tokens are like licenses that you can generate and manage without going through
the usual licensing process. Tokens let you install and test apps under development in live
cloud instances. You can also use these licenses to install and use private apps if you
only intend your app for internal use.
If your app is paid, after you install your app and apply a token, you can test your
app against various license states like valid, expired, and unlicensed.
Access token restrictions
While access tokens are like licenses, a few restrictions apply.
50-token limit:
Each app can only have 50 active tokens at a time.
Token removal:
You can delete or remove tokens at any time. If you have 50 active tokens, you can remove one
to be able to create another. Apps in cloud instances with deleted tokens are
treated as unlicensed.
No reusability:
A token is bound to a particular app and cloud instance. After a token is applied to an
Atlassian product site, it is permanently associated with that instance, and
can't be used with another.
Creating tokens
You can create a token from your app's private listing on the Marketplace. If you've already
installed the app, you can create tokens directly from the Manage listings page. If you're
generating a token to share with an external tester, you need to create the token in the Marketplace.
Generating an access token from a Marketplace listing
After you create a private listing for an app, you can generate an access token from
your listing:
Click Manage vendor account from the profile menu in the upper right.
On the Apps page, click the name of your private app.
Click on the Private listings tab.
Click Create a token.
The Private listings tab appears only for private, cloud-hosted apps. If you don't
see the button here, make sure your listing is private and cloud-hosted.
New tokens appear in the subsequent list. From here, you can either apply them manually
to an app if it's already installed, or use the link for the token to install the app
and install the app at one time. Delete tokens using the Remove button.
The Marketplace token links are installation URLs that include the token. You can share
this link with external customers or partners for testing.
Installing apps with access tokens
After generating the token, you can use the token URL to install the app and apply the token
in the same process:
Copy your token link from your Private listings page in Marketplace.
Log into the cloud instance where you want to install your app.
Go to Manage apps in the administration console.
Click Settings at the bottom of the page.
Check the box to Enable private listings.
Back in the Manage apps page, click Upload app.
Paste the URL of your descriptor from the Marketplace, and click Upload.
Your descriptor is retrieved and installed, and your token is applied. You should
see an "Installed and ready to go!" dialog.
Now you can test your app, modify its license states (if it's paid), or manage the token.
To test, set the license state to the one you want. From the License status menu, choose the
state you'd like to test - active trial, subscription, inactive subscription, etc.
The usual options for managing the subscription for your app will be disabled in the user
interface, since the token is the mechanism that serves this function for now.
Applying a token from the administration console
You can also generate a token directly from a listing directly in the product like Jira or Confluence.
You can do this from the Manage apps page in the administration console:
Follow the instructions above to Enable private listings from the Settings dialog.
Install the app using your HTTPS-hosted atlassian-connect.json descriptor URL.
Click Upload app and paste the URL into the corresponding field.
After installing the app, expand the details view for the app.
Click the plus (+) symbol next to Access token.
Log in using an account associated with your Marketplace partner profile.
Follow the in-app directions to generate and apply the token.
If you need to delete a token from an app, click the edit icon next to the token in the app view,
and clear the content and save. This deletes your token in the instance, although it still exists on the
Marketplace listing. You can disable an app in the administration console after you have
removed its token.