Skip to main content
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

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 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

​
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.