Skip to main content

Atlassian Integration Setup with nOps Business Contexts

To integrate Atlassian with nOps Business Contexts, follow these steps:

  1. Create API Key in Atlassian
  2. Set Up Integration in nOps Platform
  3. Verify Integration Requirements

Prerequisites​

Before setting up the integration, ensure you have:

  1. Atlassian Organization Access

    • Active Atlassian organization with Organization Admin role
    • Access to Atlassian Administration console (admin.atlassian.com)
    • Centralized User Management enabled (legacy user management models are not supported)

  2. Administrative Permissions

    • Organization Admin role - Required for accessing user activity and organizational data
    • Permission to create API keys
    • Access to all Atlassian products in your organization (Jira, Confluence, Bitbucket, etc.)

  3. Technical Requirements

    • Ability to create unscoped API keys (required for Admin API access)
    • Understanding that this integration requires Organization Admin access to retrieve comprehensive user data
Critical Requirements

This integration requires Organization Admin permissions - the highest level of administrative access in Atlassian. Standard user accounts or limited admin roles will not work.

Accessing Business Contexts Integrations​

To begin, navigate to the Organization Settings and click on Integrations. From there, select Business Contexts to proceed with setting up your Atlassian integration.

The list of integrations will indicate whether there are any active integrations or if the tools are not yet integrated. Active integrations will be marked accordingly, allowing you to easily identify the current status of each integration.

How the Integration Works​

  1. API Key Creation

    • Generate an API key without scopes (required for Admin API access)
    • Securely store and provide this key to nOps during integration setup

  2. Integration Setup

    • Enter a descriptive API Key Name for identification purposes
    • Configure the Atlassian API Key in nOps
    • Set an optional expiration date for your API key (up to 1 year)
    note

    Make sure to keep your API key secure and never share it with unauthorized users.

  3. Data Retrieval by nOps

    • nOps uses the provided API key to fetch usage and user activity data from Atlassian
    • Data is collected for all services associated with your Atlassian account

  4. Data Processing

    • The retrieved data is processed and displayed within the Business Contexts product
    • Usage information is organized by product, user activity, and time period

Step 1: Create API Key in Atlassian​

Administrative API keys with Organization Admin permissions are required for comprehensive access to user activity data.

  1. Access API Key Settings

    • Log in to Atlassian Administration with Organization Admin privileges
    • Navigate to Settings > API keys
    • Click Create API key

  2. Set API Key Configuration

    • Enter a descriptive name (e.g., "nOps Business Context Integration")
    • Select "API keys without scopes" - This is required because the Admin API endpoints for organization data, user directories, and activity information are not covered by the current scoped API system
    • Set expiration date (maximum 1 year)
    • Click Create API key
    important

    Critical: You must create an API key without scopes. The current scoped API system does not include access to organization data (/admin/v1/orgs), user directories (/admin/v2/orgs/.../users), and user activity endpoints (/admin/v1/orgs/.../last-active-dates) that this integration requires.

    warning

    As stated in Atlassian's Cloud Admin Scopes documentation: "Currently, scopes are not available for all APIs." The organization and user management endpoints used by this integration (/admin/v1/orgs, /admin/v2/orgs/.../users, /admin/v1/orgs/.../last-active-dates) are among those not covered by the available scopes.

    caution

    API keys expire within 1 year maximum. When this expires, you will need to generate a new key and update the integration in nOps.

  3. Save API Key

    • Copy the generated API key
    • Store it securely—API keys are typically shown only once
    caution

    Do not share your API key or expose it in public repositories. If the API key is lost, you'll need to generate a new one and update the integration.

Step 2: Set Up Integration in nOps Platform​

  1. Access the Business Contexts Integrations page in your nOps account to begin.
  2. Select the Atlassian integration card.
  3. Click on the +Add Atlassian Integration button

Configuration Parameters​

  1. Enter API Key Name

    • Provide a descriptive name for this integration (e.g., "Engineering Team Atlassian" or "Marketing Atlassian")
    • This helps identify the integration if you have multiple Atlassian accounts

  2. Enter API Key

    • Paste the API key you copied from the Atlassian platform

  3. Set Expiration Date (Optional)

    • Select an expiration date for the integration
    • The maximum allowed period is 1 year from the current date
    • If not specified, the integration will use a default expiration of 1 year

  4. Click Setup to finish

    important

    Double-check your API key. Incorrect entries will prevent synchronization.

Managing Multiple Integrations​

If you need to track usage for multiple Atlassian accounts or projects:

  1. Create Separate API Keys

    • Generate a unique API key for each Atlassian account
    • Ensure each key has the appropriate permissions

  2. Set Up Additional Integrations

    • Follow the same process to add each integration
    • Use distinct, descriptive names for each integration to easily identify them

Troubleshooting​

  1. Data Not Appearing

    • Allow up to 24 hours after setup
    • Verify Centralized User Management: Ensure your organization uses centralized (not legacy) user management
    • Check email visibility settings: Default email visibility should be set appropriately
    • Confirm there is actual user activity in your Atlassian account
    • Verify the API key is still active in Atlassian Administration

  2. Incomplete Data

    • Ensure the API key was created without scopes (unscoped keys have full Admin API access)
    • Verify Organization Admin role has access to all relevant Atlassian products
    • Check if there are any organizational restrictions or usage limits
    • Confirm Bearer Token authentication is working correctly

For support, contact nOps with your API Key Name (not the actual key) and any error messages you've encountered.

References​