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

# Atlassian

*This article applies to Atlassian connections created **after February 2026** (the Domain ID under your Lumos domain shows* `atlassian_ics`*). This is the one that appears in the Discover Tab. This integration works with both the old and new Atlassian user management experiences.*

*If your Domain ID shows* `atlassian.com`*, your connection uses the archived pre-February-2026 connector. The setup is the same , but provisioning is more limited and users created externally (e.g. via Okta) cannot be deprovisioned. Differences are called in-line.*

## After this article

You will be able to connect Atlassian to Lumos to sync users, roles, groups, and product access across your Atlassian organization, and to provision access via groups, suspend or delete users, and (with Atlassian-enabled experimental endpoints) invite users and assign platform roles.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| :- | :- | :- | :- | :- |
| Users (Directory) | Account | Yes | Yes | User accounts. Creation works by inviting a new user by email (experimental endpoint, Atlassian support must enable it) |
| Users (Managed) | Account | Yes | Yes | Managed accounts, same email-invite mechanism via the experimental endpoint |
| Roles | Permission | Yes | Yes | Platform roles, assignment requires the experimental endpoint. Only **Site Admin** (`atlassian/site-admin`) and **Org Admin** (`atlassian/org-admin`) are assignable. **User Access Admin** (`atlassian/user-access-admin`) cannot be assigned or revoked via API |
| Groups | Permission | Yes | Yes | Atlassian groups, product access is managed through groups |
| Products | Permission | Yes | No | Per-site product access (e.g. `Confluence (Site A)`, `Jira Service Management (Site B)`). Lumos also surfaces each Atlassian product as a separate managed application |

| Deprovisioning Action | Type | Description |
| :- | :- | :- |
| Deactivate | User | Suspend the user's account. The user can no longer access products, is not billed, and the license is reclaimed |
| Delete | User | Delete the user from the organization |

**Provisioning behavior:**

* **Create:** Lumos invites the user by email (the only field sent) through the experimental invite endpoint. The account stays **Pending** in Lumos until the invitation is accepted.
* **Assign or remove a group:** Lumos looks up the group's directory first, then adds or removes the membership in that directory. Groups without a directory ID can't be managed.
* **Assign or revoke a role:** only **Org Admin** (`atlassian/org-admin`) and per-site **Site Admin** (`atlassian/site-admin`) roles are accepted. Both run on the experimental role endpoints.
* **Reactivate:** Lumos restores a suspended user through the `restore-access` endpoint.
* **Remove User From All Groups:** a custom Lumos action that pages through every group the user belongs to and removes each membership, useful in offboarding workflows.

**Additional behavior:**

* **User status mapping** (Atlassian Managed Account status → Lumos):
  * `active` → Active,
  * `inactive` → Suspended,
  * `closed` → Deprovisioned,
  * User no longer returned by Atlassian → Deprovisioned.
* **Last activity:** Lumos reads `productLastAccess.lastActiveTimestamp` from the new management experience's users endpoint, falling back to the managed-accounts `last_active` timestamp on the old management experience. Per-product last login comes from `product_access.last_active`.

## Required plan and roles

* **Atlassian plan:** your organization needs at least one paid Atlassian subscription, and the **Atlassian Guard** product (formerly Atlassian Access). The Atlassian organization admin REST APIs return no user data without it. You can connect without Guard, but the integration will return no users.
* **Atlassian role:** the connecting user must be an **Organization Admin**.
* **Credential:** an organization-level **Admin API key** created at `admin.atlassian.com`, **without scopes**. A personal API token from `id.atlassian.com/manage-profile/security/api-tokens` will **not** work with the Admin APIs.
* **Experimental endpoints (optional, for full provisioning):** user invitation and platform role assignment use experimental Atlassian APIs. Contact Atlassian support to request access to `POST /v1/orgs/{orgid}/users/{userid}/role-assignments/assign`, `POST /v1/orgs/{orgid}/users/{userid}/role-assignments/revoke`, and `POST /v2/orgs/{orgid}/users/invite`. Syncing (all read operations) works without them.

## Read-only access vs provisioning

**Is read-only possible?** No. Atlassian's organization Admin REST APIs only accept an unscoped, organization-level Admin API key created by an Organization Admin, and this credential cannot be narrowed to a smaller, read-only permission set. Every connection uses the same key for both syncing and writing.

**What full provisioning requires.** The same unscoped Admin API key described above, which already covers group membership changes, user suspension, and user deletion. Inviting new users and assigning platform roles additionally require Atlassian Support to enable the experimental Role Assignment and User Invitation APIs for your organization. Syncing and the other write actions work without that extra access.

**Watch out for.** The API key's expiry is fully in your control, up to one year, and rotating or revoking it in `admin.atlassian.com` is the only way to limit its lifetime since the scope itself can't be reduced. Once SCIM is enabled with your identity provider, Atlassian blocks Lumos from deprovisioning accounts directly. Removals then have to go through the IdP instead. If your organization lacks the Atlassian Guard product, the connection succeeds but returns no user data at all.

## Instructions

**Phase 1: Create an Admin API key in Atlassian**

1. Go to [Atlassian Administration](https://admin.atlassian.com) and select the correct organization if you manage more than one.
2. Go to **Settings** → **API keys** (in some orgs this appears as **Organization settings** → **API Keys**).
3. Click **Create API key** (top right) and select an API key **without scopes**.
4. Name the key and set an **Expires on** date. The default is one week and the maximum is one year. Set it to one year to avoid the connection silently breaking.
5. Click **Create**, then copy the **Organization ID** and the **API key**. The Organization ID also appears in your organization URL: `https://admin.atlassian.com/o/<your-org-id>/overview`.

**Phase 2: Connect in Lumos**

1. Find the Atlassian card in your Lumos integrations (reconnect an existing card or add a new one).
2. Enter the **Organization ID** and paste the **API Key**.
3. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection fails / 401 Unauthorized (sometimes with an error referencing Atlassian Guard).** This is almost always a credential problem, not a Guard problem. Verify you are using an organization-level Admin API key created in `admin.atlassian.com` (not a personal API token from `id.atlassian.com`), that the key hasn't expired, been regenerated, or been deleted, that the connecting user is an Organization Admin, and that the Organization ID matches your Atlassian org (copy it with no extra spaces).

**Integration suddenly enters an error state with nothing changed.** Atlassian Admin API keys expire after a maximum of one year (one week by default). Check whether the key expired, create a new one, and update it in Lumos.

**Connected, but no users are returned.** If your organization does not have the Atlassian Guard product in its subscription, the integration connects but Atlassian returns no user data via the API.

**"Experimental API access required" error.** User invitation and platform role assignment use experimental Atlassian APIs. Contact Atlassian Support to request access to the User Invitation API and Platform Role Assignment API.

**400 error with code** `ADMIN-400-4`**.** Your org is on the old user management experience, so the integration automatically falls back to the old endpoints. This is expected behavior. On the old experience, user-to-permission associations are only made for managed accounts and functionality is more limited.

**Removing a user errors out.** Once SCIM is enabled with your identity provider, Atlassian blocks other applications from deprovisioning accounts. Removals must then go through your IdP.

**Platform role assignment fails.** Confirm experimental API access was granted by Atlassian, the role is assignable (`atlassian/site-admin` or `atlassian/org-admin`, while `user-access-admin` cannot be assigned via API), and the user is in the org. Admin roles are only surfaced when the org is on Atlassian Guard, uses Managed Accounts, the connecting account is an Org Admin, and Atlassian has enabled the role endpoints.

**A user suspended in Atlassian shows as Active in Lumos.** Lumos reads status from the data source behind Atlassian's **Managed Accounts** view, which can differ from the **User Management** tab. Atlassian exposes no API for the User Management "Suspended" (no product access) status. Use the **Product Access** column in Lumos to find users with no product access.

**Individual user roles not displayed.** Expected: Lumos manages Atlassian access primarily through groups and product access. Per-user role data is only exposed by Atlassian when the Guard + Managed Accounts + Org Admin + enabled-endpoints requirements above are met.

**A user is missing from an Access Review.** The Atlassian integration only pulls managed users. Child apps (per-product Atlassian applications) pull all users, managed and non-managed (some without emails, depending on privacy settings). Include the Atlassian-owned product apps in future Access Reviews to catch non-managed users.

**Jira project permissions aren't visible.** Lumos pulls Atlassian groups (which grant product access), but Jira project-specific permissions configured locally without group membership don't appear in the central Atlassian group view. Use the standalone Jira connector for in-product role visibility. Similarly, Lumos shows group membership but not the downstream space/project access a group grants.

**Multiple Atlassian organizations.** Each organization can be connected to Lumos as its own integration.

**Not sure which Atlassian article to follow.** Atlassian is covered by more than one Lumos connection, and each has its own setup article. This article covers the core Atlassian organization connector, which syncs users, groups, roles, and product access across the whole organization. Jira user and group provisioning is a separate connection with its own article, and Jira ITSM (ticketing) is a third, separate connection. Check the Domain ID on the integration card in Lumos to confirm which connection you are configuring before you follow any setup steps.