Last updatedNov 20, 2019

App descriptor

The app descriptor is a JSON file (atlassian-connect.json) that describes the app to the Atlassian application. The descriptor includes general information for the app, as well as the modules that the app wants to use or extend.

If you're familiar with Java app development with previous versions of the Atlassian Plugin Framework, you may already be familiar with the atlassian-plugin.xml descriptors. The atlassian-connect.json serves the same function.

The descriptor serves as the glue between the remote app and the Atlassian application. When an administrator for a cloud instance installs an app, what they are really doing is installing this descriptor file, which contains pointers to your service. You can see an example below.

For details and application-specific reference information on the descriptor please refer to the Jira modules and Confluence modules sections of this documentation. But we'll call out a few highlights from the example here.

Since Atlassian Connect apps are remote and largely independent from the Atlassian application, they can be changed at any time, without having to create a new version or report the change to the Atlassian instance. The changes are reflected in the Atlassian instance immediately (or at least at page reload time).

However, some app changes require a change to the descriptor file itself. For example, an app could be modified to have a new page module. Since this requires a page module declaration in the descriptor, it means making an updated descriptor available. Until that updated descriptor is re-installed into the Atlassian Product that change in the descriptor file will not take effect. To propagate a change in the descriptor to the Atlassian products, you need to create a new version of the app in its Marketplace listing. The Marketplace will take care of the rest: informing administrators and automatically installing the available update. See Upgrades for more details.

Descriptor JSON schemas

The descriptor format for apps to each product is defined by a JSON schema.

Validator tool

Atlassian Connect provides a stand-alone validation service for app descriptors.

The validator will check that your descriptor is syntactically correct. Just paste the JSON content of your descriptor in the descriptor field, and select the Atlassian product you want to validate against.

App descriptor structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "modules": {},
  "key": "my-app-key",
  "name": "My Connect App",
  "description": "A connect app that does something",
  "vendor": {
    "name": "My Company",
    "url": "http://www.example.com"
  },
  "links": {
    "self": "http://www.example.com/connect/jira/atlassian-connect.json"
  },
  "lifecycle": {
    "installed": "/installed",
    "uninstalled": "/uninstalled"
  },
  "baseUrl": "http://www.example.com/connect/jira",
  "authentication": {
    "type": "jwt"
  },
  "enableLicensing": true,
  "scopes": [
    "read",
    "write"
  ]
}
authentication

Type: Authentication

Required: Yes

Description: Defines the authentication type to use when signing requests between the host application and the connect app.

baseUrl

Type: string (uri)

Required: Yes

Description: The base url of the remote app, which is used for all communications back to the app instance. Once the app is installed in a product, the app's baseUrl cannot be changed without first uninstalling the app. This is important; choose your baseUrl wisely before making your app public.

The baseUrl must start with https:// to ensure that all data is sent securely between our cloud instances and your app.

Note: each app must have a unique baseUrl. If you would like to serve multiple apps from the same host, consider adding a path prefix into the baseUrl.

key

Type: string (^[a-zA-Z0-9-._]+$)

Required: Yes

Description: A unique key to identify the app.This key must be <= 64 characters.

apiVersion

Type: integer

Description: The API version is an OPTIONAL integer. If omitted we will infer an API version of 1.

The intention behind the API version is to allow vendors the ability to beta test a major revision to their Connect app as a private version, and have a seamless transition for those beta customers (and existing customers) once the major revision is launched.

Vendors can accomplish this by listing a new private version of their app, with a new descriptor hosted at a new URL.

They use the Atlassian Marketplace's access token facilities to share this version with customers (or for internal use). When this version is ready to be taken live, it can be transitioned from private to public, and all customers will be seamlessly updated.

It's important to note that this approach allows vendors to create new versions manually, despite the fact that in the common case, the versions are automatically created. This has a few benefits-- for example, it gives vendors the ability to change their descriptor URL if they need to (the descriptor URL will be immutable for existing versions)

description

Type: string

Description: A human readable description of what the app does. The description will be visible in the Manage Apps section of the administration console. Provide meaningful and identifying information for the instance administrator.

enableLicensing

Type: boolean

Defaults to: false

Description: Whether or not to enable licensing options in the UPM/Marketplace for this app.

lifecycle

Type: Lifecycle

Description: Allows the app to register for app lifecycle notifications.

links

Type: object

Description: A set of links that the app wishes to publish

1
2
3
4
5
6
{
  "links": {
    "self": "https://app.domain.com/atlassian-connect.json",
    "documentation": "https://app.domain.com/docs"
  }
}

modules

Type: object

Description: The list of modules this app provides.

name

Type: string

Description: The human-readable name of the app.

scopes

Type: [string, … ]

Description: Set of scopes requested by this app.

1
2
3
4
5
6
{
  "scopes": [
  "read",
  "write"
  ]
}

vendor

Type: App Vendor

Description: The vendor who is offering the app.

Authentication

Defines the authentication type to use when signing requests from the host application to the Connect app.

Example

1
2
3
4
5
{
  "authentication": {
    "type": "jwt"
  }
}

Properties

type

Type: string

Defaults to: jwt

Allowed values:

  • jwt
  • JWT
  • none
  • NONE
  • Description: The type of authentication to use.

    Lifecycle

    Allows an app to register callbacks for events that occur in the lifecycle of an installation. When a lifecycle event is fired, a POST request will be made to the appropriate URL registered for the event.

    The installed lifecycle callback is an integral part of the installation process of an app, whereas the remaining lifecycle events are essentially webhooks.

    Each property in this object is a URL relative to the app's base URL.

    Lifecycle attribute example

    1
    2
    3
    4
    5
    6
    {
      "installed": "/installed",
      "uninstalled": "/uninstalled",
      "enabled": "/enabled",
      "disabled": "/disabled"
    }

    Lifecycle HTTP request payload

    Lifecycle callbacks contain a JSON data payload with important tenant information that you will need to store in your app in order to sign and verify future requests. The payload contains the following attributes:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {
      "key": "installed-addon-key",
      "clientKey": "unique-client-identifier",
      "sharedSecret": "a-secret-key-not-to-be-lost",
      "serverVersion": "server-version",
      "pluginsVersion": "version-of-connect",
      "baseUrl": "https://example.atlassian.net",
      "displayUrl": "https://docs.example.com",
      "productType": "jira",
      "description": "Atlassian Jira at https://example.atlassian.net",
      "serviceEntitlementNumber": "SEN-number",
      "eventType": "installed"
    }
    AttributeDescription
    keyApp key that was installed into the Atlassian Product, as it appears in your app's descriptor.
    clientKeyIdentifying key for the Atlassian product instance that the app was installed into. This will never change for a given instance, and is unique across all Atlassian product tenants. This value should be used to key tenant details in your app. The one time the clientKey can change is when a backup taken from a different instance is restored onto the instance. Determining the contract between the instance and app in this situation is tracked by AC-1528 in the Connect backlog.
    publicKeyDeprecated This is the public key for this Atlassian product instance. This field is deprecated and should not be used.
    accountIdThe account ID for identifying users in the `sub` claim sent in JWT during calls. This is the user associated with the relevant action, and may not be present if there is no logged in user.
    sharedSecretUse this string to sign outgoing JWT tokens and validate incoming JWT tokens. Optional: and may not be present on non-JWT app installations, and is only sent on the installed event. All instances of your app use the same shared secret.
    serverVersionThis is a string representation of the host product's version. Generally you should not need it.
    pluginsVersionThis is a semver compliant version of Atlassian Connect which is running on the host server, for example: 1.1.15.
    baseUrlURL prefix for this Atlassian product instance. All of its REST endpoints begin with this `baseUrl`.
    displayUrl

    If the Atlassian product instance has an associated custom domain, this is the URL through which users will access the product. Any links which an app renders server-side should use this as the prefix of the link. This ensures links are rendered in the same context as the remainder of the user's site.

    This field may not be present, in which case the baseUrl value should be used. API requests from your App should always use the baseUrl value and not be based on the URL specified here.

    productTypeIdentifies the category of Atlassian product, e.g. jira or confluence.
    descriptionThe host product description - this is customisable by an instance administrator.
    serviceEntitlementNumber (optional)Also known as the SEN, the service entitlement number is the app license ID. This attribute will only be included during installation of a paid app.
    oauthClientIdThe OAuth 2.0 client ID for your app. For more information, see OAuth 2.0 - JWT Bearer token authorization grant type

    App vendor

    Gives basic information about the app vendor

    1
    2
    3
    4
    5
    6
    {
      "vendor": {
        "name": "Atlassian",
        "url": "http://www.atlassian.com"
      }
    }

    Properties

    name

    Type: string

    Description: The name of the app vendor. Supply your name or the name of the company you work for.

    url

    Type: string (uri)

    Description: The URL for the vendor's website.