Skip to main content
Version: 0.10

Atlassian users (WIP)

Pulls the user directory for an Atlassian Cloud organisation, including product access, role assignments, MFA state and last-active dates.

Type nameatlassian_users
CreatesUsers
Runs onA sensor with outbound reach to api.atlassian.com and your Atlassian site
Presence flagatlassian_user_exists
Field prefixatlassian_

What it contributes​

  • Identity: account ID, display name, email, account type, account origin (Internal, External, Service desk customer, App or Former)
  • Organisation: organisation, job title, department, groups and group names, org roles, service desk customer organisations
  • Access: product access, product activity, license, paid products, product roles, admin roles, Guard billable flag, the Jira projects the account can browse and their count, Atlassian products used outside the site (Trello, Bitbucket, other sites)
  • Account state: active, status, organisation status, deactivated on, membership status, email verified, claim status, MFA enabled, for-deletion flag
  • Credentials: API tokens held, active API tokens, their labels, when one was last used
  • AI use: Atlassian MCP calls and Rovo calls within the AI activity window, the AI clients and MCP tools used, last AI activity
  • Organisation policy: how many authentication policies the organisation has; 0 means no SSO and no enforced two-step verification
  • Lifecycle: added to org, last active
  • Locale: time zone, locale

It writes the shared user fields user_email, user_full_name and updated_at, and user_title, user_department and user_organization only where the user does not already hold a value from another source. The last time the account used any product is the sighting it reports for last_seen, and the date it joined the organisation is its first_seen.

An enrichment the run could not read, such as API tokens without the matching scope, is left out rather than written as empty, so an earlier scan's values stay.

MFA state and the license are the two fields to filter on

atlassian_mfaEnabled is a direct control gap when false. atlassian_license combined with atlassian_last_active finds seats being paid for and not used. Neither is visible anywhere else in the inventory.

Guard billable is not a product seat

Guard billable (atlassian_access_billable) is Atlassian's flag for Atlassian Guard billing. Guard counts a managed account that uses any Atlassian product, Trello and Bitbucket included, so an account with no seat on the site can be Guard billable. Use License to see who takes a seat.

Former accounts are left out by default

An account the organisation no longer holds arrives with a name and nothing else, so the scan template's Include former accounts is off by default.

Matching​

Each account is matched to an existing user by its Atlassian account ID, then by its Atlassian email, then by its email against the shared user_email. An account that matches nothing creates a new user, subject to the template's On New Asset Discovered action.

Requirements​

The integration is outbound-only: it is a scheduled API client, so nothing is installed in the Atlassian organisation and nothing has to reach into the deployment.

Network access​

FromToProtocolPort
The sensor running the integrationapi.atlassian.com: the organisation's directory, roles, activity, API tokens, audit log and policiesHTTPS over TCP443
The sensor running the integrationYour site, e.g. company.atlassian.net: site users, groups, projects and service desk organisationsHTTPS over TCP443

Two hosts, because Atlassian splits the directory across the organisation API and the site itself, the same split that makes two credentials necessary. If the sensor reaches the internet through a proxy, point Proxy settings at it rather than opening direct egress.

Access in Atlassian​

NeedWhy
An organisation admin accountCreating the organisation API key is an organisation admin task, and the directory, role-assignment and last-active endpoints are admin-scoped. See Permissions in Atlassian
The ability to create a user API token for the sitePaired with the account's email as basic auth against the site
The ability to create an organisation API tokenA separate admin key, with read-only scopes, for the organisation-level endpoints; the two are not interchangeable
The organisation IDRead from the admin console URL — not the site name, as the warning under Permissions in Atlassian explains

In this deployment​

NeedWhy
A registered, healthy sensorThe integration runs on a sensor, on the platform's schedule — see Sensors

There are no special host requirements beyond a sensor that is checking in. Note that per-user directory and role calls make the run scale with directory size, and Collect project access costs one request per Jira project, rather than with anything on the sensor host.

Configuration​

This integration needs two credentials, because Atlassian splits the directory across two APIs.

FieldRequiredNotes
NameYesLabel for this instance
Atlassian DomainYesYour site, e.g. company.atlassian.net
Atlassian EmailYesEmail of the account owning the API token
API TokenYesUser API token for the site
Organization API TokenYesKey for the Atlassian Admin API, with the read-only scopes listed under Permissions in Atlassian
Organization IDYesAtlassian organisation ID
Proxy settingsNohttp://host:port
SensorYesSensor that will run the integration
Ignore SSLYesSkips certificate validation

API Token and Organization API Token are write-only: once saved, the console shows a locked box with Replace and never displays them again.

Scan template options​

The scan template's advanced settings choose which accounts to import and which optional sources to read:

OptionDefaultEffect
Include apps and botsOnImports app accounts: Rovo agents, Automation, Slack, Trello and other integrations
Include service desk customersOnImports portal-only Jira Service Management customers
Include former accountsOffImports accounts the organisation no longer holds, which the site still lists as former users
Collect API tokensOnRecords each person's API tokens. Needs the read:tokens:admin scope
Collect AI activityOnCounts each person's Atlassian MCP and Rovo use from the audit log. Needs the read:events:admin scope
AI activity window (days)30How many days of audit log the AI activity covers. 0 turns the collection off
Collect service desk organizationsOnRecords the customer organisation of each service desk customer. Read only when service desk customers are included
Collect project accessOnRecords the Jira projects each account can browse, for up to 1,000 projects. Costs one request per project

An optional source that fails is reported as a warning on the scan and left out; the run carries on.

Two tokens, two scopes of access

The API token is a personal token for the site, paired with the email address as basic auth. The organization API token is an admin key that authorises the organisation-level endpoints. They are created in different places and are not interchangeable.

Permissions in Atlassian​

The account holding the organisation API token must be an organisation admin — the directory, role-assignment and last-active endpoints are all admin-scoped. Read-only scopes are enough for the organisation API key: read:orgs:admin, read:directories:admin, read:domains:admin, read:policies:admin, read:events:admin and read:tokens:admin.

From the organisation API (api.atlassian.com/admin, with the organisation API token) the integration reads:

EndpointProvides
/v1/orgs/{orgId}/usersThe managed accounts, with billing and product activity
/v2/orgs/{orgId}/directories/-/users/searchEvery person in the organisation's directories
/v2/orgs/{orgId}/directories/-/users/{accountId}The full directory entry, for apps and deactivated accounts
/v2/orgs/{orgId}/directories/-/users/{accountId}/role-assignmentsOrg role assignments
/v1/orgs/{orgId}/directory/users/{accountId}/last-active-datesLast-active dates per product
/api-access/v1/orgs/{orgId}/api-tokensAPI tokens, as metadata: the token values are never readable
/v1/orgs/{orgId}/eventsAudit-log events for MCP and Rovo use
/v1/orgs/{orgId}/policiesAuthentication policies

From the site (with the email and API token) it reads /rest/api/3/users/search and /rest/api/3/user for the site's accounts and groups, /rest/api/3/project/search and /rest/api/3/user/permission/search for project access, /rest/servicedeskapi/organization for service desk organisations, and /rest/api/3/applicationrole for seat counts.

Test connection checks the site credential against the user search, then the organisation API token against the organisation itself and its directory search, and names the permission or scope that is missing (Browse users and groups, read:orgs:admin or read:directories:admin).

TODO

Confirm the site permissions the email and API token's account needs beyond Browse users and groups: for the project permission search, the service desk organisation list and the application roles (seat counts). Also confirm which scope covers the managed-account list, the role assignments and the last-active dates, and whether read:domains:admin is needed, since no domain endpoint is called.

Organisation ID is not the site name

Find it in the admin console URL at admin.atlassian.com/o/<orgId>/. Using the site domain in its place produces 404s on every organisation endpoint while the site-level token still authenticates, so the run looks half-working.

TODO

Document the API-token rotation story: Atlassian tokens can be given an expiry, and the failure mode for an expired org token versus an expired user token differs.

See also​