Client identification

API clients are programs that act on behalf of users to access data. While client identification is not strictly required, it does help Atlassian to troubleshoot problems faster, customers to better manage their security exposure, and developers to get better answers to tricky problems. For example, many Atlassian API clients use a default user agent string provided by whatever HTTP library they are using. However, multiple programs may be written with Python Requests, all sending indistinguishable user agent headers. This makes it harder to sort the traffic from your integration, from whatever customers and other integrations may be sending.

Origin ID for links to Atlassian UI

Identify HTML links into our product user interface with a unique atlOrigin query string parameter added to the URL. This is similar to the UTM parameter used for click tracking in marketing web sites. In this context, uniqueness is guaranteed by Atlassian issuing the origin ID. For example, if linking into Jira’s Issue page:

1
2
https://devpartisan.atlassian.net/browse/TIS-11?atlOrigin=abc123

We generate a unique value for each integration so if you have more than 1 integration, please make sure we have properly associated each integration to a different origin value.

We do not recommend using this parameter in REST APIs or OAuth 2.0 flows, where this parameter might not be properly ignored.

HTTP User Agent for REST API requests

Identify HTTP clients making REST API requests with a unique user agent HTTP header. In this context, uniqueness is not guaranteed. Instead, uniqueness is based on following convention:

1
2
{atlassian product}-{source product}-int/{version} ({optional})

atlassian product

If the integration is multi-product, this can be as broad as atlassian. Or, for integration with specific products, name that product like jira, or jirasoftware. This helps us understand the scope of impact for API problems.

source product

If the integration is multi-product, this can be as broad as microsoft. Or, for integration with specific products, name that product like visualstudiocode, or just code. This lets us know who to contact in case of API problems and should be sufficient unique to find all related API requests and responses for diagnosis.

int

Short for integration as a category of REST API clients. This helps us understand usage this set of similar clients.

version

The version of your API integration, in case there may be multiple versions deployed at the same time. Following semantic versioning is a helpful clue when trouble-shooting.

optional

If you want to send additional client metadata, put it in parenthesis. For example, if you use multiple HTTP libraries for different requests and wanted to more specifically identify the underlying code. As a full header, that might look like User-Agent: jirasoftware-jellyfish-int/1.7.3 (requests/2.24).

While standard HTTP headers allow for mixed case and spaces, we recommend all lower case and no spaces to help with tracking in our log files. For example:

1
2
User-Agent: jira-code-int/1.0.0

We also recommend using the same User Agent header, regardless of technology. For example, you might have a microservice in Python that makes HTTP GET requests, and another in Java for dispatching webhooks as HTTP POST requests. If both work together as "Jira integration", use the same User Agent header in both. The same applies for development and testing tools, like curl. Sending the same User Agent header will help identify your requests. Alternatively, you may identify the different clients in the optional segment, keeping the starting segment the same.

This convention is for programs acting REST API clients, not browser clients.

OAuth 2 client registration

Identify OAuth 2.0 (3LO) clients with a unique client ID. In this context, uniqueness is guaranteed by Atlassian issuing the origin ID in the App management user interface. This client ID is not affected by the Name given to an App.

While this mechanism is unique identification of your App for the purpose of REST API authentication, we also recommend the above identification mechanisms to help with monitoring and troubleshooting. OAuth 2.0 (3LO) is exclusive of Connect Apps. Clients will either use OAuth 2 or the authentication associated with Connect, but not both.

Atlassian Connect App key

Identify Connect Apps with a unique key in the App descriptor. In this context, uniqueness is not guaranteed. Instead, uniqueness is based on following convention (the same convention as the first segment of the user agent header):

1
2
{atlassian product}-{source product}-int

atlassian product

Connect Apps are constrainted to a specific product. For example, jira. This helps us understand the scope of impact for API problems.

source product

If the integration is multi-product, this can be as broad as microsoft. Or, for integration with specific products, name that product like visualstudiocode, or just code. This lets us know who to contact in case of problems and should be sufficient unique to find all related API requests and responses for diagnosis.

int

Short for integration as a category of Connect Apps. This helps us understand usage this set of similar clients.

While this mechanism is unique identification of your App for the purpose of Connect App authentication, we also recommend user agent headers and origin ID query parameters to help with monitoring and troubleshooting. Connect Apps are exclusive with OAuth 2.0 (3LO). Clients will either use the authentication associated with Connect or OAuth 2, but not both.