> 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. Go to **Settings** and open the **API keys** section.
3. Select **Create API key** at the top right. Use this standard API key flow - 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 **Integrations** and select **Atlassian Admin** from the SaaS Applications list.
9. Click **Connect**, enter your **Organization ID** and **Org API key (unscoped)**, and save.

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. You can also trigger a manual sync at any time from the integration settings page in Harmony.

### Disconnecting the integration

To remove the Atlassian Admin API integration:

1. In Harmony, go to **Integrations** and find the Atlassian Admin connection.
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 **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 and update the credentials in Harmony under **Integrations** - **Atlassian Admin** - **Edit**.

**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 accesses Atlassian data in read-only mode and does not modify any data in your Atlassian organization
* 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.