API Reference

Org Enumerator Tool - Complete execution guide and JSON reference

Why the Org Enumerator is Required

Forge Architecture Limitation

Atlassian Forge apps run in a sandboxed environment and cannot access Organization-level APIs due to security architecture constraints. This means A9 Sightglass can analyze your Jira and Confluence data, but not cross-workspace organization structure.

Forge App (Sandboxed)

  • ✅ Jira Projects & Issues
  • ✅ Confluence Spaces & Pages
  • ✅ Site-level Users & Groups
  • ✅ Permissions & Security Settings
  • ❌ Organization Structure
  • ❌ Cross-workspace Analysis
  • ❌ Enterprise Hierarchy
→

Org Enumerator (External Tool)

  • ✅ Organization Hierarchy
  • ✅ All Workspaces/Sites
  • ✅ Cross-workspace Users
  • ✅ Enterprise-level Groups
  • ✅ Domain Policies
  • ✅ SSO Configuration

What You Gain with Org Enumerator Data

Without Org Data

  • Single-site security analysis
  • Project-level compliance checks
  • Limited user visibility
  • No cross-workspace insights

With Org Data

  • Enterprise-wide security posture
  • Organization compliance reporting
  • Complete user lifecycle tracking
  • Cross-workspace risk analysis
  • Domain policy enforcement
  • Comprehensive audit trails

Prerequisites

Required Permissions

Atlassian Account Requirements 
Organization Administrator role required to access:
- Organization API endpoints
- User management across all sites
- Domain and security policies
- Cross-workspace reporting

System Requirements

  • Node.js: Version 14 or higher
  • Internet Connection: Access to api.atlassian.com
  • API Token: Atlassian API token with Org Admin scope

Installation

Download the Tool

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

You can also download the tool directly from your browser: org-enumerator.js

Verify the Download

Terminal 
node org-enumerator.js --version

Execution Instructions

Step 1: Generate API Token

  1. Go to Atlassian API Tokens
  2. Click Create API token
  3. Name it "A9 Sightglass Org Enumerator"
  4. Copy the token immediately (it won't be shown again)

Step 2: Set Environment Variables

Terminal (macOS/Linux) 
export ATLASSIAN_EMAIL='your-email@company.com'
export ATLASSIAN_API_TOKEN='your-api-token-here'
export ATLASSIAN_ORG_ID='your-org-id'
PowerShell (Windows) 
$env:ATLASSIAN_EMAIL='your-email@company.com'
$env:ATLASSIAN_API_TOKEN='your-api-token-here'
$env:ATLASSIAN_ORG_ID='your-org-id'
Finding Your Organization ID

Visit admin.atlassian.com and copy the ID from the URL: admin.atlassian.com/o/org-id-here/overview

Step 3: Run the Enumerator

Terminal 
node org-enumerator.js --output org-data.json

Command Options

Option Description Default
--output Output filename for JSON data org-data.json
--verbose Enable detailed logging false
--include-inactive Include inactive users in export false
--version Display version information -
--help Display help information -

Example: Verbose Output with Inactive Users

Terminal 
node org-enumerator.js \
  --output org-data.json \
  --verbose \
  --include-inactive

Understanding the Output

What Gets Collected

Organization Structure

  • Organization name and ID
  • All workspaces/sites
  • Site URLs and types
  • Site status and health

User Information

  • User accounts and emails
  • Account status (active/inactive)
  • Last activity timestamps
  • Site access matrix

Groups & Permissions

  • Organization-level groups
  • Group memberships
  • Cross-site permissions
  • Role assignments

Security Policies

  • Domain verification status
  • SSO configuration
  • IP allowlists
  • Access policies

Sample Output

org-data.json (excerpt) 
{
  "organization": {
    "id": "org-abc123",
    "name": "Acme Corporation",
    "url": "https://admin.atlassian.com/o/org-abc123"
  },
  "sites": [
    {
      "id": "site-123",
      "url": "https://acme.atlassian.net",
      "type": "jira",
      "status": "active",
      "users": 245
    }
  ],
  "users": [
    {
      "accountId": "user-456",
      "email": "john.doe@acme.com",
      "displayName": "John Doe",
      "status": "active",
      "lastActive": "2025-01-15T14:30:00Z",
      "sites": ["site-123", "site-124"]
    }
  ],
  "groups": [
    {
      "id": "group-789",
      "name": "Engineering",
      "members": 45,
      "sites": ["site-123"]
    }
  ],
  "policies": {
    "domainVerified": true,
    "ssoEnabled": true,
    "ipAllowlist": ["203.0.113.0/24"]
  }
}

Uploading to A9 Sightglass

Upload from Settings

  1. Open A9 Sightglass in Jira or Confluence
  2. Click the Settings icon (gear) in the top right
  3. Go to the Organization Data tab
  4. Click Upload JSON File
  5. Select your org-data.json file
  6. Click Process and Save
Automatic Processing

Once uploaded, A9 Sightglass will automatically merge the organization data with your Jira/Confluence analysis to provide enterprise-wide insights.

What Happens After Upload

1

Data Validation

Schema validation ensures the JSON format is correct

2

Data Merging

Organization data is merged with Jira/Confluence data

3

Analysis Enhancement

New cross-workspace security insights become available

4

Dashboard Update

Dashboard refreshes with enhanced visualizations and reports

JSON Schema Reference

Top-Level Structure

TypeScript Interface 
interface OrgEnumeratorOutput {
  organization: Organization;
  sites: Site[];
  users: User[];
  groups: Group[];
  policies: SecurityPolicies;
  metadata: Metadata;
}

Organization

Field Type Description
id string Unique organization identifier
name string Organization display name
url string Admin portal URL

Site

Field Type Description
id string Unique site identifier
url string Site URL (e.g., acme.atlassian.net)
type enum "jira" | "confluence" | "jira-service-management"
status enum "active" | "inactive" | "suspended"
users number Total user count for this site

User

Field Type Description
accountId string Atlassian account ID
email string User email address
displayName string User display name
status enum "active" | "inactive" | "suspended"
lastActive string ISO 8601 timestamp of last activity
sites string[] Array of site IDs user has access to

Automation & CI/CD

Scheduled Execution

Run the Org Enumerator on a schedule to keep your analysis up-to-date.

Cron Job (Linux/macOS)

crontab -e 
# Run daily at 2 AM
0 2 * * * cd /path/to/enumerator && node org-enumerator.js --output org-data.json

GitHub Actions

.github/workflows/org-scan.yml 
name: Org Data Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM
  workflow_dispatch:

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - name: Download Enumerator
        run: curl -O https://a9sightglass.io/org-enumerator.js
      
      - name: Run Enumerator
        env:
          ATLASSIAN_EMAIL: ${{ secrets.ATLASSIAN_EMAIL }}
          ATLASSIAN_API_TOKEN: ${{ secrets.ATLASSIAN_API_TOKEN }}
          ATLASSIAN_ORG_ID: ${{ secrets.ATLASSIAN_ORG_ID }}
        run: node org-enumerator.js --output org-data.json
      
      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: org-data
          path: org-data.json

Programmatic Upload

You can also upload the JSON programmatically using the A9 Sightglass API:

curl 
curl -X POST https://your-site.atlassian.net/gateway/api/a9-sightglass/org-data \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @org-data.json

Troubleshooting

Common Issues

Error: "Unauthorized - Invalid API token"

Solution:
  • Verify your API token is still valid
  • Ensure you're using the correct email address
  • Check that the token has Organization Admin permissions
  • Regenerate the token if necessary

Error: "Organization ID not found"

Solution:
  • Verify the organization ID from admin.atlassian.com
  • Ensure you have access to the organization
  • Check for typos in the environment variable

Error: "Rate limit exceeded"

Solution:
  • Wait a few minutes before retrying
  • Consider running the tool during off-peak hours
  • Contact support if rate limits are consistently hit

Upload fails in A9 Sightglass

Solution:
  • Verify the JSON file is valid (use node -c org-data.json)
  • Check file size (max 10 MB)
  • Ensure you have admin permissions in A9 Sightglass
  • Try re-running the enumerator to generate fresh data

Getting Help

Support Resources

Need additional help? Contact us at support@a9consulting.com or visit our support page.

Questions? Contact Support