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

# Atlassian (Confluence & JIRA)

> Connect Confluence and JIRA to Omni

The Atlassian connector enables Omni to index and search content from your organization's Confluence and JIRA instances.

## Overview

### What Gets Indexed

| Source     | Content                                         |
| ---------- | ----------------------------------------------- |
| Confluence | Pages, blog posts, comments, and attachments    |
| JIRA       | Issues, comments, descriptions, and attachments |

### How It Works

1. An Atlassian service-account token accesses the Atlassian REST APIs through the Atlassian API gateway
2. The connector syncs content based on project and space permissions
3. Permission inheritance ensures users only see content they have access to in Atlassian
4. Optional Atlassian organization-admin credentials improve account and group resolution when Atlassian Guard is available

<Note>
  The connector uses read-only access. Omni cannot modify any content in your Atlassian instance.
</Note>

## Prerequisites

Before setting up the Atlassian connector, ensure you have:

* **Atlassian Cloud account** (Confluence and/or JIRA)
* **Admin access** to your Atlassian organization
* **Atlassian service account** with access to the Confluence spaces and JIRA projects you want to index
* **Service account token** created from Atlassian Administration
* Optional: **Atlassian Guard** and an organization admin API key for richer directory sync

## Setup

### Step 1: Create a Service Account Token

1. Open [Atlassian Administration](https://admin.atlassian.com)
2. Go to **Security** → **Service accounts**
3. Create a service account for Omni
4. Generate a service account API token
5. Copy the generated token immediately — you won't be able to see it again

<Warning>
  Use a service account token, not a personal Atlassian API token. Service account tokens usually start with `ATSTT`; personal account tokens usually start with `ATATT` and are not the supported auth model for this connector.
</Warning>

Grant the service account read access to the Confluence spaces and JIRA projects you want Omni to index. Omni filters the service account itself out of indexed permission lists so it does not become an end-user access grant.

### Step 2: Gather Your Atlassian Details

You'll need the following information:

| Field                      | Description                                                        | Example                                |
| -------------------------- | ------------------------------------------------------------------ | -------------------------------------- |
| Atlassian Domain           | Your Atlassian Cloud domain                                        | `your-company.atlassian.net`           |
| Service Account Token      | The token you created in Step 1                                    | `ATSTT...`                             |
| Organization ID            | Optional. Atlassian organization UUID for org-admin directory sync | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| Organization Admin API Key | Optional. Admin API key for Atlassian Guard directory APIs         | `...`                                  |

<Tip>
  Your Atlassian domain is the URL you use to access Confluence or JIRA, without the `https://` prefix.
</Tip>

<Note>
  The optional organization-admin fields require Atlassian Guard. When they are absent, Omni falls back to per-site Atlassian APIs for account-to-email and group resolution.
</Note>

### Step 3: Connect to Omni

1. Navigate to **Settings** → **Integrations** in Omni
2. Find **Atlassian** and click **Connect**
3. Enter your details:
   * **Atlassian Domain**: Your Atlassian Cloud domain (e.g., `your-company.atlassian.net`)
   * **Service Account Token**: The token you created in Step 1
   * Optional **Organization ID** and **Organization Admin API Key**
4. Click **Connect**

### Step 4: Configure Sources

After connecting, you need to configure which Atlassian products to index:

1. Click **Settings** next to Confluence or JIRA
2. Choose which spaces (Confluence) or projects (JIRA) to include or exclude
3. Save the source settings
4. Click **Sync** and wait for the initial sync to complete

<Check>
  Your Atlassian connector is now configured. Initial indexing may take a while depending on the amount of content in your Confluence and JIRA instances.
</Check>

***

## Managing the Integration

### Viewing Sync Status

Navigate to **Settings** → **Integrations** to view the sync status for each source directly on the list, including last sync time, number of indexed items, and any errors. Click **Settings** on a source for more details and sync history.

### Rotating API Tokens

It's recommended to rotate API tokens periodically for security.

1. Create a new service account token in Atlassian Administration
2. Update the token in Omni settings
3. Revoke the old token in Atlassian

### Removing the Integration

1. Navigate to **Settings** → **Integrations**
2. Click **Settings** against the Atlassian source
3. Click **Delete Permanently**
4. Optionally, revoke the API token in [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed">
    Common causes:

    * Service account token was copied incorrectly — create a new one and try again
    * A personal API token was used instead of a service account token
    * Token has been revoked or expired

    Verify your credentials by testing the API directly:

    ```bash theme={null}
    curl -H "Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN" \
      "https://api.atlassian.com/ex/jira/YOUR_CLOUD_ID/rest/api/3/myself"
    ```
  </Accordion>

  <Accordion title="Domain not found">
    Ensure you're using the correct Atlassian Cloud domain:

    * Use `your-company.atlassian.net` (without `https://`)
    * Check that you're using Atlassian Cloud, not a self-hosted Data Center instance
  </Accordion>

  <Accordion title="Missing content">
    If some content isn't appearing:

    * Verify the space or project is included in your configuration
    * Check that the admin account has access to the content
    * Archived spaces and projects may need to be explicitly included
    * Wait for the sync cycle to complete (check sync status)
  </Accordion>

  <Accordion title="Permission errors">
    The service account must be granted access to the Atlassian content you want indexed:

    * Ensure the service account has access to all spaces and projects you want to index
    * Consider using a dedicated service account with broad read access
  </Accordion>

  <Accordion title="Sync taking too long">
    Initial sync duration depends on:

    * Number of Confluence pages and JIRA issues
    * Amount of attachments
    * API rate limits

    For large instances (10,000+ items), initial sync may take several hours. Monitor progress in the Omni admin panel.
  </Accordion>
</AccordionGroup>

## Security Considerations

* **Read-only access**: Use a dedicated service account with read access to the Atlassian content you want indexed
* **Permission inheritance**: Users only see content they can access in Atlassian
* **Token security**: Service account tokens and org-admin API keys should be treated like passwords
* **Token rotation**: Rotate tokens periodically (recommended every 90 days)
* **Audit logging**: Monitor API token usage in Atlassian's admin panel

## What's Next

<CardGroup cols={3}>
  <Card title="Search Your Data" icon="magnifying-glass" href="/user-guide/search">
    Learn how to search across Confluence and JIRA content
  </Card>

  <Card title="AI Assistant" icon="robot" href="/user-guide/ai-assistant">
    Ask questions about your documentation and issues
  </Card>

  <Card title="Add More Connectors" icon="plug" href="/connectors/overview">
    Connect additional data sources
  </Card>
</CardGroup>