Security overview

Security helps protect customer data from unauthorized access and from malicious or accidental changes. It also allows administrators to install apps with confidence, letting users enjoy the benefits of apps without worry.

Security has two key parts:

Authentication tells the host product the identity of your app or integration.
Authorization determines what actions your app or integration can take within the host product.

Authentication and authorization methods differ depending on whether you are building an Atlassian Connect app or another type of integration.

If you are building a Connect app, read Security for Connect apps.
If your Connect app needs to act on behalf of the user, read User impersonation for Connect apps.
If you are creating a non-Connect app in the developer console, read OAuth 2.0 authorization code grants (3LO).
If you are writing a simple script or making REST API calls yourself, read Basic auth for REST APIs.

These methods are summarized below.

Authentication for Connect apps

Atlassian Connect apps use JWT (JSON Web Tokens) for authentication. This technology is built into the supported Atlassian Connect libraries. If you use the client frameworks, most security operations are handled for you. Otherwise, you will need to construct and manage JWT tokens yourself. See Understanding JWT for Connect apps.

Authorization for Connect apps

Atlassian Connect apps can use two types of authorization:

Authorization via scopes and app users: Scopes are permissions that are defined in the app descriptor. The app has its own app user with permissions controlled by the admin. The set of allowed actions is the intersection of the scopes and the permissions of the app user. This is the normal authorization method, which you should use unless you need to make server-to-server requests on behalf of a user.
Authorization with user impersonation: User impersonation allows your integration to access Atlassian APIs on a user's behalf. You should only use this method when your app needs to make server-to-server requests on behalf of a user.

Authorization via scopes and app users

This method relies on two types of authorization:

Static authorization via scopes
Run-time authorization via app users

You define scopes in the app descriptor to specify the maximum set of actions that an app may perform: read, write, etc. This security level is enforced by Atlassian Connect and cannot be bypassed by app implementations. To learn more, read our page on scopes.

How scopes and permissions work together

The set of actions that an app is capable of performing is the intersection of the statically defined scopes and the permissions of the user assigned to the request. This means that requests can be rejected because the assigned user lacks the required permissions. Therefore, your app should always defensively detect HTTP 403 forbidden responses from the product.

Every app is assigned its own app user in a Cloud instance. In general, server-to-server requests are made by the app user. Client-side requests are made as the current user in the browser session, and are supported via the AP.request() method.

To learn more, read Security for Connect apps.

If the app needs to act on behalf of the user, you can make server-to-server requests using OAuth 2.0 user impersonation (see next section).

Connect apps cannot access private personal data by using OAuth 2.0 JWT or AP.request().

Authorization with user impersonation

User impersonation allows your integration to access Atlassian APIs on a user's behalf. This is provided via the JWT Bearer token authorization grant type for OAuth 2.0, which is also known as two-legged OAuth with impersonation (2LOi). At a high level, this method works by the app exchanging a JWT for an OAuth 2.0 access token (provided by the application). The access token can be used to make server-to-server calls, on behalf of the user, to the application's API.

To learn more, read User impersonation for Connect apps.

Security for other integrations

Connect is not the only solution for integrating with Atlassian products. External applications or services, scripts, or even bots, can access Atlassian APIs directly. We recommend using OAuth 2.0 authorization code grants (3LO) for these types of integrations, although authentication with an API token is available for writing scripts or making REST API calls manually.

OAuth 2.0 authorization code grants (3LO)

OAuth 2.0 authorization code grants, also known as three-legged OAuth, is a token-based method for authentication and authorization. This method allows your integration to access Atlassian APIs on a user's behalf. Unlike two-legged OAuth, three-legged OAuth involves the end user in the authorization process by asking them to consent to access to their data.

Authenticated access is provided by an access token that is used to make calls to the API. OAuth 2.0 authorization code grants require an app created in the developer console. This app provides the authentication credentials that are used to get an access token for the desired API.

Authorization for OAuth 2.0 authorization code grants is implemented via scopes. Scopes statically specify the maximum set of actions that an app may perform (see scopes). Note, OAuth 2.0 authorization code-only scopes are different to Connect scopes.

To learn more, read OAuth 2.0 (3LO) for apps.

Basic authentication

Basic authentication uses an API token to authenticate the client. The token is generated from a user's Atlassian Account, encoded, then added to the header for requests to the API.

Authorization for basic authentication is based on the permissions of the user you used to generate the API token. For example, if you are using basic authentication, your user must have the Admin permission for a space in order to call PUT /wiki/rest/api/space/{spaceKey} (Update space).

We recommend that you don't use basic authentication. It may be easier to implement, but it is much less secure. Consider using OAuth 2.0 authorization code grants (3LO) instead.

To learn more, read Basic auth for REST APIs.