Atlassian users (WIP)
Pulls the user directory for an Atlassian Cloud organisation, including product access, role assignments, MFA state and last-active dates.
| Type name | atlassian_users |
| Creates | Users |
| Runs on | A sensor with outbound reach to api.atlassian.com and your Atlassian site |
| Presence flag | atlassian_user_exists |
| Field prefix | atlassian_ |
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.
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 (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.
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
| From | To | Protocol | Port |
|---|---|---|---|
| The sensor running the integration | api.atlassian.com: the organisation's directory, roles, activity, API tokens, audit log and policies | HTTPS over TCP | 443 |
| The sensor running the integration | Your site, e.g. company.atlassian.net: site users, groups, projects and service desk organisations | HTTPS over TCP | 443 |
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
| Need | Why |
|---|---|
| An organisation admin account | Creating 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 site | Paired with the account's email as basic auth against the site |
| The ability to create an organisation API token | A separate admin key, with read-only scopes, for the organisation-level endpoints; the two are not interchangeable |
| The organisation ID | Read from the admin console URL — not the site name, as the warning under Permissions in Atlassian explains |
In this deployment
| Need | Why |
|---|---|
| A registered, healthy sensor | The 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.
| Field | Required | Notes |
|---|---|---|
| Name | Yes | Label for this instance |
| Atlassian Domain | Yes | Your site, e.g. company.atlassian.net |
| Atlassian Email | Yes | Email of the account owning the API token |
| API Token | Yes | User API token for the site |
| Organization API Token | Yes | Key for the Atlassian Admin API, with the read-only scopes listed under Permissions in Atlassian |
| Organization ID | Yes | Atlassian organisation ID |
| Proxy settings | No | http://host:port |
| Sensor | Yes | Sensor that will run the integration |
| Ignore SSL | Yes | Skips 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:
| Option | Default | Effect |
|---|---|---|
| Include apps and bots | On | Imports app accounts: Rovo agents, Automation, Slack, Trello and other integrations |
| Include service desk customers | On | Imports portal-only Jira Service Management customers |
| Include former accounts | Off | Imports accounts the organisation no longer holds, which the site still lists as former users |
| Collect API tokens | On | Records each person's API tokens. Needs the read:tokens:admin scope |
| Collect AI activity | On | Counts each person's Atlassian MCP and Rovo use from the audit log. Needs the read:events:admin scope |
| AI activity window (days) | 30 | How many days of audit log the AI activity covers. 0 turns the collection off |
| Collect service desk organizations | On | Records the customer organisation of each service desk customer. Read only when service desk customers are included |
| Collect project access | On | Records 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.
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:
| Endpoint | Provides |
|---|---|
/v1/orgs/{orgId}/users | The managed accounts, with billing and product activity |
/v2/orgs/{orgId}/directories/-/users/search | Every 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-assignments | Org role assignments |
/v1/orgs/{orgId}/directory/users/{accountId}/last-active-dates | Last-active dates per product |
/api-access/v1/orgs/{orgId}/api-tokens | API tokens, as metadata: the token values are never readable |
/v1/orgs/{orgId}/events | Audit-log events for MCP and Rovo use |
/v1/orgs/{orgId}/policies | Authentication 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).
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.
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.
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
- Azure users — Entra ID identities, which most Atlassian accounts will also have
- Integrations overview — the shared configuration model