Org Enumerator

A lightweight Node.js script that collects organization-level data from Atlassian's admin APIs and produces an encrypted file you upload into A9 Sightglass — unlocking a deeper tier of analysis and reporting.

A9 Sightglass works without the Org Enumerator. All site-level analysis — Jira users, groups, permissions, projects, workflows, and compliance checks — runs entirely through the Forge app. The Org Enumerator is an optional add-on that fills in the organization-wide picture Forge cannot reach on its own.

Why It Exists

Atlassian Forge apps run inside a strict, server-side sandbox. Forge grants each app credentials scoped to a single site (e.g., yourcompany.atlassian.net). That is intentional — it limits what a compromised or malicious Marketplace app can access.

However, Atlassian also exposes a separate set of Organization APIs at api.atlassian.com/admin/v1/orgs/…. These endpoints sit above the site layer. They describe the parent organization that can own multiple sites, manage enterprise policies, verify domains, and maintain a directory of all managed accounts across every product.

Forge cannot call these endpoints. The sandbox does not expose the bearer token or OAuth scope needed to authenticate against the Organization API. This is not a bug or an oversight — it is an architectural boundary Atlassian has drawn deliberately to separate site-scoped apps from organization-level administration. 

 Atlassian Cloud Organization
 ┌──────────────────────────────────────────────────────────────┐
 │                                                              │
 │   Organization APIs  api.atlassian.com/admin/v1/orgs/…      │
 │   ─ /users        ─ /policies    ─ /domains                 │
 │   ─ /directories  ─ /events      ─ /workspaces              │
 │                        │                                     │
 │          NOT accessible from Forge sandbox                  │
 │                        │                                     │
 │   ┌─────────┬──────────┴──────────┬─────────┐               │
 │   │  Site A │      Site B         │ Site C  │               │
 │   │  (Jira) │   (Confluence)      │ (Jira)  │               │
 │   │         │                     │         │               │
 │   │ ┌─────┐ │                     │         │               │
 │   │ │Forge│ │                     │         │               │
 │   │ │ App │ │   Forge is scoped   │         │               │
 │   │ │     │ │   to Site A only    │         │               │
 │   │ └─────┘ │                     │         │               │
 │   └─────────┴─────────────────────┴─────────┘               │
 └──────────────────────────────────────────────────────────────┘

 Org Enumerator runs OUTSIDE Forge, authenticates with your
 Atlassian API token, then produces an encrypted file you
 upload into the app.

What You Get

The table below shows which data products are available with the Forge app alone versus with Org Enumerator data loaded.

Forge app (always available)

  • Site users & group memberships
  • Project permissions & roles
  • Issue security schemes
  • Permission scheme analysis
  • Workflow configuration audit
  • Application access settings
  • Sankey permission-flow diagrams
  • Compliance rule evaluation
  • Security posture score
  • PDF & CSV report generation

Unlocked by Org Enumerator

  • Organization-wide user directory
  • Managed account status & lifecycle
  • Cross-site access inventory
  • Enterprise domain verification
  • Org-level security policies
  • SSO & SCIM configuration state
  • Dormant account detection (org-wide)
  • Permission Matrix report (full)
  • Organization hierarchy visualization
  • Audit event history

How It Works

The Org Enumerator is a single-file Node.js script you run from your own machine or CI pipeline. It never phones home to A9 servers. Data flows like this:

1
You provide credentials locally

Set three environment variables — your admin email, an Atlassian API token, and your Organization ID. These never leave your machine.

2
The script calls Atlassian Organization APIs

It enumerates orgs, directories, groups, users, domains, policies, events, and workspaces via paginated requests directly from your machine to api.atlassian.com.

3
Data is encrypted locally with AES-256-GCM

Before writing to disk the script encrypts the entire payload with a passphrase you choose. Key derivation uses PBKDF2 (100 000 iterations, SHA-256) with a random salt. No PII is logged to stdout at any point.

4
You upload the encrypted file into A9 Sightglass

In the app: Settings → Organization Data → Upload. Provide the same passphrase and the app decrypts and ingests the data client-side inside the Forge sandbox.

5
The app joins org data with site data

A9 Sightglass merges the org-level directory with Jira site data to produce the full set of reports, including the Permission Matrix, cross-site access inventory, and org hierarchy Sankey.

The API Boundary in Detail

Understanding which APIs are accessible from Forge and which require external authentication helps explain both the architecture and the security model.

API endpoint Access tier From Forge?
/rest/api/3/users/search Site Yes
/rest/api/3/group/bulk Site Yes
/rest/api/3/permissionscheme Site Yes
/rest/api/3/project/{id}/role Site Yes
/admin/v1/orgs Org No — requires Org Admin bearer token
/admin/v1/orgs/{id}/users Org No — requires Org Admin bearer token
/admin/v1/orgs/{id}/policies Org No — requires Org Admin bearer token
/admin/v1/orgs/{id}/domains Org No — requires Org Admin bearer token
/admin/v1/orgs/{id}/directories Org No — requires Org Admin bearer token
/admin/v1/orgs/{id}/events Org No — requires Org Admin bearer token

Forge's OAuth 2.0 scopes cover the site-tier endpoints on the left. The org-tier endpoints on the right require a separate Atlassian admin API token authenticated against api.atlassian.com with organization admin permissions. There is no mechanism for a Forge app to request or hold those credentials.

Privacy & Security

No data sent to A9 servers AES-256-GCM encryption PBKDF2 key derivation Zero PII logged to console Open source script

The Org Enumerator script is designed to be auditable and transparent. Your API token is read from environment variables and is only used to make direct HTTPS requests to api.atlassian.com. It is never written to disk or included in the output file.

The encrypted output file contains user account metadata (email addresses, display names, account IDs, managed status) along with policy and domain configuration. Handle this file according to your organization's data-retention policies and delete it once the upload to Sightglass is complete.

API token scope: The token needs Organization Admin permissions in admin.atlassian.com. Create a dedicated service-account token for this purpose rather than using a personal admin token, and rotate it regularly.

Setup Steps

1. Prerequisites

  • Node.js 18 or later (node --version to check)
  • Organization Admin access in admin.atlassian.com
  • An Atlassian API token scoped to organization admin

2. Create an API Token

  1. Visit id.atlassian.com → API tokens
  2. Click Create API token, name it A9 Org Enumerator
  3. Copy the token immediately — it will not be shown again

3. Find Your Organization ID

  1. Go to admin.atlassian.com
  2. Select your organization from the dropdown
  3. Look at the URL: https://admin.atlassian.com/o/<org-id>/
  4. The UUID after /o/ is your Organization ID

4. Configure Environment Variables

export ATLASSIAN_EMAIL=admin@yourcompany.com
export ATLASSIAN_API_TOKEN=your-api-token-here
export ATLASSIAN_ORG_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
You can also place these in a .env file in the same directory as the script. Never commit that file to version control.

5. Run the Script

node org-enumerator.js

The script will print progress counters (no PII) and write an encrypted .json file to the current directory when complete.

6. Upload to A9 Sightglass

  1. Open A9 Sightglass inside Jira
  2. Go to Settings → Organization Data
  3. Click Upload Organization Data
  4. Select the encrypted .json file
  5. Enter the passphrase you chose during encryption
  6. Click Process

7. Schedule Regular Updates (optional)

For ongoing monitoring, schedule the script to run periodically so Sightglass always reflects the current state of your organization: 

# Run daily at 2 AM (cron)
0 2 * * * cd /path/to/org-enumerator && node org-enumerator.js

Download

The Org Enumerator is a single self-contained JavaScript file. No package installation is required.

org-enumerator.js

Single-file Node.js 18+ script — no npm install required

Download Script

Or fetch it directly from the terminal:

curl -O https://a9sightglass.io/org-enumerator.js

The script is intentionally kept as a single auditable file with no external dependencies beyond Node.js built-ins (fs, crypto, process). Review it before running it — that is by design.

Troubleshooting

401 Unauthorized

Your API token is invalid or expired. Verify the token at id.atlassian.com and ensure ATLASSIAN_EMAIL matches the account that created the token.

403 Forbidden

The account does not have Organization Admin permissions. Verify at admin.atlassian.com that your account shows as an organization admin.

Empty results / zero users

Check that your Organization ID is correct (the UUID from the /o/ segment of the admin URL, not a site ID). Also confirm that your organization has verified at least one domain — managed accounts only appear after domain verification.

Rate limiting

The script includes automatic back-off. For very large organizations you can increase the delay between requests: 

RATE_LIMIT_DELAY=1000 node org-enumerator.js
Still stuck?

Open a ticket at the JSM Support Portal or email support@a9sightglass.io with your Node.js version, the error message, and whether you can reach admin.atlassian.com manually.