License import API for server apps

If your server app used a non-Atlassian licensing system before becoming a paid-via-Atlassian app, you can convert your proprietary license keys into new Marketplace license keys. To convert an existing license into a Marketplace license, you use the Atlassian License Service API, as described here.

Before starting

Before you can use the Atlassian License Service API, you need to be approved for access by the Atlassian Marketplace team. This is necessary because the Atlassian Marketplace team audits usage and monitors the performance of the API very closely, subject to the Atlassian Marketplace Vendor Agreement.

To be approved for access, file an issue in the Marketplace Vendor Support Portal. Keep an eye on the issue (or watch for notifications) to find out when you are ready to go.

Converting proprietary licenses into Marketplace licenses

After getting the go-ahead from the Marketplace team, use the Atlassian License Service API as described here. The service accepts JSON data via HTTP POST and returns a JSON response.

The URL for the service is:

1
2
https://marketplace.atlassian.com/rest/1.0/plugins/KEY/license

In your request:

Replace KEY with the your app key. This is the same key you supplied when submitting your app to the Marketplace. It also appears in the app descriptor (atlassian-plugin.xml) for your app.
Ensure the Content-Type is application/json.
Provide credentials via HTTP basic authentication. You can use the same username and password that you do to access your vendor account on the Atlassian Marketplace.

In request body, provide details about the license to be migrated. For example, for a 2000-user commercial license, the body would look like this:

1
2
{
  "id": "1000",
  "email": "customer@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "organisationName": "Example Customer",
  "isoCountryCode": "US",
  "startDate": "2011-05-01",
  "endDate": "2012-05-01",
  "licenseType": "COMMERCIAL",
  "users": 2000
}

And a successful response would look like this:

1
2
{
  "id": "1000",
  "sen": "SEN-4839484",
  "licenseKey": "888BKQ0OD8oPeNpVj11Lwz8U08GytI1qJ8Z2I=X02eu"
}

Request format

The service accepts the following values in the request.

Make sure that the data you submit in your request is formatted as indicated in the table. For example, dates must be in `yyyy-MM-dd` format. Submitting incorrectly formatted data does not necessarily generate a service error and can lead to faulty or invalid licenses.

Field	Required	Type	Description
`id`	yes	String	A unique license identifier. The identifier prevents accidentally importing the same license twice. This can be any non-empty string; it only must be unique within the set of all licenses for this particular app.
`email`	yes	String	The licensee's (end customer's) email address. If there is not already an Atlassian account with this email address, the service creates one.
`firstName`, `lastName`, `organisationName`	yes	String	The licensee's (end customer's) identifying information. Used to create the new account on my.atlassian.com. This is only done if the account did not previously exist. If the account exists, the service ignores these fields.
`address1`, `address2`, `city`, `state`, `postcode`	no	String	Address information. Used for licensees (end customers) without an account on my.atlassian.com. The service creates the new account with this data. Otherwise, if the account exists, the system ignores this information.
`isoCountryCode`	yes	String	The ISO code for the licensee's (end customer's) country. The service can only import a licenses for Marketplace-authorized countries.
`startDate`	yes	String	The date on which support for this license started. This value must have a format of: `yyyy-MM-dd`.
`endDate`	yes	String	The date on which support for this license ends. This value must have a format of: `yyyy-MM-dd`.
`licenseType`	yes	String	Must be `COMMERCIAL` or `ACADEMIC`.
`users`	yes	Integer	The maximum number of users (or, for Bamboo, the maximum number of remote agents) supported by this license, or `-1` for no maximum. This should match one of the user tiers for the host product.
`expertEmail`	no	String	If set, the imported license will be associated with the Atlassian Solution Partner organization associated to this email address.

Notes:

The times you specify will be set to midnight Sydney time on that day. This might be as much as a day ahead relative to the location of your customer.
In light of the discontinuation of the legacy Enterprise licensing program, this service generates app licenses that are compatible with both enterprise and non-enterprise host licenses.

Successful response

An HTTP 200 status indicates the license was converted successfully. The JSON response body contains the following:

Item	Description
`id`	The same unique identifier specified in the request.
`sen`	The new Support Entitlement Number for this license.
`licenseKey`	The encoded Marketplace-license key.

Error responses

If the call fails, the service returns one of the following HTTP statuses:

Item	Description
`400 (Bad Request)`	Reasons for this error include: the request did not contain a valid JSON object, the `startDate` of the imported license is within the last 30 days, the `expertEmail` is not a valid Atlassian Solution Partner email address, or a required field was omitted. If available, the response returns additional detail about the error.
`401 (Unauthorized)`	You did not provide valid basic authentication credentials.
`403 (Forbidden)`	The credentials you provided were not associated with the vendor of the specified app or the vendor is not authorized to use the API.
`404 (Not Found)`	The app key you specified in the URL does not correspond to any app listed on the Atlassian Marketplace.
`409 (Conflict)`	A license with the same `id` already exists. The response body contains the same JSON information as it would for a successful import. This allows you to view the license key and SEN for an existing license.