> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Atlassian

## What's Supported

### Supported Actions

For Jira, the following is supported:

* [Read Actions](/read-actions), including full historic backfill and incremental read.
* [Write Actions](/write-actions).
* [Proxy Actions](/proxy-actions), using the base URL `https://api.atlassian.com`.

### Supported Objects

The Atlassian connector supports writing to and reading from Jira **Issues**.

### Example Integration

For an example manifest file of a Jira integration, visit our [samples repo on Github](https://github.com/amp-labs/samples/blob/main/jira/amp.yaml).

## Before You Get Started

To integrate Atlassian Jira with Ampersand, you will need [an Atlassian Account](https://id.atlassian.com/signup).

Once your account is created, you'll need to create an app in Atlassian, configure the Ampersand redirect URI within the app, and obtain the following credentials from your app:

* Client ID
* Client Secret
* Scopes

You will then use these credentials and scopes to connect your application to Ampersand.

### Create an Atlassian Account

Here's how you can sign up for an Atlassian account:

* Go to the [Atlassian Sign Up page](https://www.atlassian.com/try/cloud/signup?bundle=jira-software\&edition=free\&skipBundles=true) and create an account.
* Sign up using your preferred method.

### Creating an Atlassian App

Follow the steps below to create an *Atlassian* app:

1. Go the [Atlassian Developer Console My Apps Page](https://developer.atlassian.com/console/myapps/).
2. Click the **Create** dropdown to create a new app.
3. Select **Oauth 2.0 integration**.
4. Enter the **App Name**.
5. Select the  **I agree to be bound by Atlassian's developer terms.** checkbox.
6. Click **Create**.

   <br />

   <img src="https://mintcdn.com/ampersand-24eb5c1a/Bx3tggG51e0liOp-/images/provider-guides/491e169-Jira1.gif?s=94d005a59165a6729179f7139405b8ee" alt="Alt text" width="1440" height="702" data-path="images/provider-guides/491e169-Jira1.gif" />

### Adding Scopes in your Atlassian App

You need to define the necessary permissions for your Atlassian app by selecting and adding required scopes, to allow Ampersand to access data effectively. You can limit the access to only the specific scopes needed for your application.

Follow the steps below to add scopes to your Atlassian App:

1. In the [Atlassian Developer Console My Apps Page](https://developer.atlassian.com/console/myapps/), select your app.
2. Go to **Permissions**.
3. Select the scopes for your application. Atlassian will authorize access to the selected scopes for your application.

<img src="https://mintcdn.com/ampersand-24eb5c1a/Bx3tggG51e0liOp-/images/provider-guides/5d6df49-Jira2.gif?s=dc30bcea5a356b97c3716e69b3860377" alt="Alt text" width="1440" height="702" data-path="images/provider-guides/5d6df49-Jira2.gif" />

For more information on the scopes, go to [Scopes](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/)  section in the Atlassian documentation.

### Adding Ampersand Redirect URL in Your App

Follow the steps below to add the Ampersand redirect URL in your Atlassian app:

1. In the [Atlassian Developer Console My Apps Page](https://developer.atlassian.com/console/myapps/), select your app.
2. Go to **Authorization**.
3. Next to **OAuth 2.0 (3LO)**, click **Add**.
4. Enter the Ampersand **Callback URL**: `https://api.withampersand.com/callbacks/v1/oauth`.
5. Click **Save changes**.

<img src="https://mintcdn.com/ampersand-24eb5c1a/p4alBfPjHeNuBPh1/images/provider-guides/1bb01c8-Jira3.gif?s=905cd3cf9b7bfddc34bacb3afc162d0d" alt="Alt text" width="1440" height="702" data-path="images/provider-guides/1bb01c8-Jira3.gif" />

You'll find the **Client ID** and **Client Secret** keys for your app in the **Settings** section.

<img src="https://mintcdn.com/ampersand-24eb5c1a/p4alBfPjHeNuBPh1/images/provider-guides/2a2bd9f-Screenshot_2024-06-26_at_16.51.34.png?fit=max&auto=format&n=p4alBfPjHeNuBPh1&q=85&s=9decc2e7d898d4742f82d6b395415595" alt="Alt text" width="2050" height="474" data-path="images/provider-guides/2a2bd9f-Screenshot_2024-06-26_at_16.51.34.png" />

You'll use these credentials while connecting your app to Ampersand.

## Add Your Atlassian App Info to Ampersand

1. Log in to your [Ampersand Dashboard](https://dashboard.withampersand.com).

2. Select the project where you want to create a Atlassian integration.

   <img src="https://mintcdn.com/ampersand-24eb5c1a/CkzFg-K1u4gYx3ZD/images/provider-guides/dd47b7a-Ampersand.png?fit=max&auto=format&n=CkzFg-K1u4gYx3ZD&q=85&s=d580aa00cc421fe14cfbab79c2e0812f" alt="Alt text" width="2244" height="442" data-path="images/provider-guides/dd47b7a-Ampersand.png" />

3. Select **Provider apps**.

4. Select *Atlassian* from the **Provider** list.

5. Enter the previously obtained *Client ID* in the **Client ID** field and the *Client Secret* in the **Client Secret** field.

6. Enter the scopes set for your application in *Atlassian*. In addition to the scopes you configured, **you must add the `offline_access` scope.**

7. Click **Save changes**.

## Using the connector

To start integrating with Atlassian:

* Create a manifest file like the [example](https://github.com/amp-labs/samples/blob/main/jira/amp.yaml).
* Deploy it using the [amp CLI](/cli/overview).
* If you are using Read Actions, create a [destination](/destinations).
* Embed the [InstallIntegration](/embeddable-ui-components#install-integration) UI component.
* Start using the connector!
  * If your integration has [Read Actions](/read-actions), you'll start getting webhook messages.
  * If your integration has [Write Actions](/write-actions), you can start making API calls to our Write API.
  * If your integration has [Proxy Actions](/proxy-actions), you can start making Proxy API calls.