Last updated Mar 18, 2024

Connect 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.

The descriptor file can only be fetched from web server ports 80, 443, or 8080.

App descriptor updates

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

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.

Updates to the app descriptor are published to the Marketplace automatically a few minutes after you publish changes to your descriptor file. We regularly poll the app descriptor URL that you included when you submitted your listing. When a change is detected, we update your app in the Atlassian Marketplace with a new version.

The Marketplace will automatically inform administrators of the change and install 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

The app descriptors can be validated using our interactive JSON schema validation tool, with the above descriptors.

The validator will check that your descriptor is syntactically correct. Just paste the JSON content of your descriptor in the interactive editor, and any issues with the schema will be shown inline in the editor view.

App descriptor structure

1
2
{
  "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"
  ],
  "cloudAppMigration": {
    "migrationWebhookPath" : "/app-migration-events-webhook"
  }
}

Changing the fields in the app descriptor will automatically create a new app version in the Marketplace. Learn more on Marketplace updates.

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.

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

Max Length: 1400<

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 { "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. The app's name is visible to customers and must therefore be consistent with the name used to distribute the app such as any listing in the Atlassian Marketplace. Immutable records are created during the first installation of an app, one of which includes the name of the app. It is therefore important that the name of the app is correct as it can not be changed.

scopes

Type: [string, … ]

Description: Set of scopes requested by this app. { "scopes": [ "read", "write" ] }

vendor

Type: App Vendor

Description: The vendor who is offering the app.

cloudAppMigration

Type: Cloud App Migration

Description: Contains information for App Migrations

Authentication

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

Example

1
2
{
  "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
    {
      "installed": "/installed",
      "enabled": "/enabled",
      "disabled": "/disabled",
      "uninstalled": "/uninstalled"
    }
    
    LifecycleTriggered eventDescription
    installed App installation Initial app installation to a site. A new sharedSecret is created for each installation event.
    App upgrade

    Upraded to a new app version, and a new sharedSecret is created for your app to update.

    This can either be triggered by a user or by automatic app update process

    Secret rotation Manually triggered to rotate the shared secret to mitigate any security concerns. A new sharedSecret is created for your app to update.
    Site rename Atlassian product url is renamed. App receives an installed lifecycle callback with a new baseUrl
    App install following site import

    Atlassian product is imported from another site. New clientKey and sharedSecret are created for the site.

    If there is an existing installation record for a site(Atlassian product's baseUrl) under a different clientKey, your app should associate the site with the new clientKey and the sharedSecret

    enabled

    App enabled

    App is enabled and users can start using the app

    Triggered after a successful app installation or upgrade. This event will not be triggered for any other type of installed lifecycle events.

    disabled

    App disabled

    App is disabled before performing uninstallation
    uninstalled

    App uninstalled

    App is uninstalled successfully from a site.

    Note: Authentication for installed/uninstalled lifecycle requests

    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
    {
      "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://issues.example.com",
      "displayUrlServicedeskHelpCenter": "https://support.example.com",
      "productType": "jira",
      "description": "Atlassian Jira at https://example.atlassian.net",
      "serviceEntitlementNumber": "SEN-number",
      "entitlementId": "Entitlement-Id",
      "entitlementNumber": "Entitlement-Number",
      "eventType": "installed",
      "installationId": "ari:cloud:ecosystem::installation/uuid-of-forge-installation-identifier"
    }
    
    AttributeDescription
    keyApp key that was installed into the Atlassian Product, as it appears in your app's descriptor.
    clientKey Identifying key for the Atlassian product tenant that the app was installed into. This will never change for an Atlassian product tenant. However, be aware that importing data into a site will result in a new tenant. In this case, any app installations into the new tenant (using the same baseUrl as the previous tenant) will result in an installation payload containing a different clientKey. 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. A new secret is shared for each installation event.
    serverVersionDeprecated This is a string representation of the host product's version. Generally you should not need it.
    pluginsVersionDeprecated This 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`. Do not use the `baseUrl` as an identifier for the Atlassian product as this value may not be unique.
    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.

    If a custom domain is not configured, this field will still be present but will be the same as the baseUrl. Note that API requests from your App should always use the baseUrl value.

    displayUrlServicedeskHelpCenter

    If the Atlassian product instance has an associated custom domain for Jira Service Desk functionality, this is the URL for the Jira Service Desk Help Center. Any related 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 user's Jira Service Desk.

    If a custom domain is not configured, this field will still be present but will be the same as the baseUrl. Note that API requests from your App should always use the baseUrl value.

    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.

    Note: This value is deprecated and will be removed

    entitlementId (optional)The license entitlement ID is the app license ID. This attribute will only be included during installation of a paid app.
    entitlementNumber (optional)The license number is the app license number. 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
    installationIdThe unique Forge installation ID, included only for apps that are registered on Forge . Unlike the clientKey, this identifier changes in the event of a reinstallation, but persists across site imports. Refer to the source of either of the official Atlassian Connect frameworks for guidance on how to associate these identifiers, allowing for differences in their lifecycles.

    App vendor

    Gives basic information about the app vendor

    1
    2
    {
      "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.

    Cloud App Migration

    Defines settings to be used for App Migration

    1
    2
    {
      "cloudAppMigration": {
        "migrationWebhookPath" : "/app-migration-events-webhook"
      }
    }
    

    Properties

    migrationWebhookPath

    Type: string (uri)

    Description: Relative URL path where App Migration Webhook events will be sent to

    Rate this page: