> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/atlassian-admin-api.md).

# Atlassian (Admin API)

The Atlassian Admin API integration connects your Atlassian organization directly to Harmony, giving you richer visibility into how your team uses Atlassian products - without relying on a third-party connector. Once connected, Harmony surfaces license, activity, and user data across your entire Atlassian organization, helping you understand adoption, manage access, and make informed decisions about your Atlassian spend.

### What data is synced

When you connect your Atlassian organization, Harmony collects the following data:

* **User directory** - the managed accounts in your organization, with name, email, and account status. Accounts that are closed (deprovisioned) in Atlassian are not collected, and neither are accounts that hold no licensed product access
* **License types per product** - see which users are licensed for Jira, Jira Service Management, Jira Customer Service, Jira Product Discovery, Confluence, Bitbucket, Atlassian Assets, Atlassian Rovo, Opsgenie, Statuspage, Trello, and Loom. Any other Atlassian product is grouped under a single **Atlassian** entry
* **Plan tier** - the plan behind each product workspace (Free, Standard, Premium, or Enterprise). Products that carry no entitlement in your organization report an unknown tier
* **Last activity** - the most recent date each account was active in each product, used as the last-login signal for identifying unused seats
* **Platform roles** - the Atlassian organization roles each account holds: organization admin, site admin, and user access admin
* **Sign-in activity** - successful logins from your organization's audit log, attributed to the product the login was made against, including the IP address and the city, region, and country the login came from

{% hint style="warning" %}
**Sign-in activity requires Atlassian Guard.** Atlassian only emits login events in the organization audit log for organizations with an Atlassian Guard (Standard or Premium) subscription, or at least one product on an Enterprise plan. On other organizations the integration still connects and still syncs users, licenses, and last-activity dates, but no login events will ever appear - Atlassian returns an empty audit log rather than an error.
{% endhint %}

{% hint style="info" %}
**Platform roles are organization-level only.** Harmony collects the organization admin, site admin, and user access admin roles. Product-level administrators - such as Jira project admins or Confluence space admins - are not exposed by these endpoints and are not collected.
{% endhint %}

### Prerequisites

Before you connect, make sure you have:

* An active Atlassian organization
* Organization admin permissions in Atlassian Administration (`admin.atlassian.com`) - required to create an organization API key
* The ability to create an **unscoped** organization API key. Atlassian also offers a newer **API keys with scopes** flow; keys created that way are not supported by this integration
* For sign-in activity only: an Atlassian Guard (Standard or Premium) subscription, or at least one product on an Enterprise plan

### Connecting Atlassian to Harmony

Follow these steps to set up the direct integration:

1. Sign in to [Atlassian Administration](https://admin.atlassian.com) and select your organization.
2. Select **Organization settings**, then **API keys**.
3. Select **Create API key**, select **API keys without scopes**, then select **Create API key**. Do not use **API keys with scopes**, because Harmony requires an unscoped organization API key.
4. Enter a name you will recognize later (for example, `Harmony Integration`).
5. Set an expiry date under **Expires on**. By default the key expires **one week** from the day you create it, and you cannot select a date more than a year from creation. Pick the longest date your security policy allows, and plan to rotate the key before it expires.
6. Select **Create**.
7. Copy both the **Organization ID** and the **API key** - Atlassian will not show them to you again. Your Organization ID also appears in the URL of your Atlassian Administration dashboard (`admin.atlassian.com/o/<organization-id>`).
8. In Harmony, go to **Settings** > **Integrations**, find **Atlassian Admin** under **SaaS Applications** (or search for it by name), and click its card.
9. Enter your **Organization ID** and **Org API key (unscoped)**, then click **Connect**.

Harmony will begin syncing data from your Atlassian organization. The initial sync may take a few minutes depending on the size of your user directory. On the first connection, Harmony backfills up to 90 days of sign-in history where it is available.

### Permissions required

The API key used for this integration must be created by a user with **organization admin** permissions in Atlassian Administration. An organization admin is the highest level of admin in Atlassian and can complete any administrative task in Atlassian Administration. Without these permissions, Harmony will not be able to retrieve license, role, or user directory data.

### Data refresh

After the initial sync, Harmony refreshes your Atlassian user, license, and role data every 6 hours, and checks the organization audit log for new sign-in events every hour.

### Disconnecting the integration

To remove the Atlassian Admin API integration:

1. In Harmony, go to **Settings** > **Integrations** and click the **Atlassian Admin** card.
2. Click **Disconnect** and confirm your choice.
3. Optionally, revoke the API key in Atlassian Administration to ensure it can no longer be used.

Disconnecting the integration stops all future data syncs. Historical data already collected in Harmony is retained according to your workspace data retention settings.

### Troubleshooting

**Sync fails immediately after connecting** Verify that the API key was created by a user with organization admin permissions. Keys created by users with lower privilege levels will not have access to the required endpoints.

**API key is rejected** Harmony requires an unscoped organization API key, created from **Organization settings** > **API keys** in Atlassian Administration. If the key was created through the **API keys with scopes** flow, create a new unscoped key and update the credentials in Harmony.

**Organization ID not accepted** Make sure you are copying the Organization ID shown when the API key was created, or from the URL in Atlassian Administration (`admin.atlassian.com/o/<organization-id>`), and not a site-level identifier.

**API key expired** Atlassian API keys have an expiry date set at creation time, and the default is only one week from the day the key was created. The maximum is one year. If your key has expired, generate a new one in Atlassian Administration, then in Harmony open the **Atlassian Admin** card under **Settings** > **Integrations**, click **Replace** next to **Org API key (unscoped)**, paste the new key, and click **Save Changes**.

**No sign-in or login activity appears** Login events are only written to the Atlassian organization audit log for organizations with an Atlassian Guard (Standard or Premium) subscription, or at least one product on an Enterprise plan. Without one, Atlassian returns an empty audit log, so no login activity will appear even though the integration is connected and other data is syncing normally. Confirm your subscription in Atlassian Administration.

**Only partial product data is visible** Harmony surfaces data for the products active in your Atlassian organization. If a product does not appear, confirm it is provisioned and has active licenses within your organization. Products that Atlassian reports no entitlement for will appear with an unknown plan tier.

### Data & Privacy

For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).

* Harmony reads your Atlassian organization data to sync it. It changes your Atlassian organization only when a workflow you build runs an Atlassian action, such as inviting a user or adding a user to a group or removing them from one
* Sign-in events collected from the Atlassian audit log include the originating IP address and the city, region, and country resolved from it
* The integration can be revoked at any time by disconnecting it in Harmony or revoking the API key in Atlassian Administration


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/saas-applications/atlassian-admin-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
