User Management and License Optimizer for Jira and ConfluenceUser Management and License Optimizer for Jira and Confluence

Organization API Key

The Organization API Key is the foundation of User Management & License Optimizer's functionality. This key enables the app to connect with your Atlassian organization and manage users, groups, and licenses across all sites. Without a valid API key, the app cannot operate.

Overview

The Organization API Key serves as the secure connection between User Management & License Optimizer and your Atlassian Cloud organization. This key provides the necessary permissions to:

  • Access user and group data across all sites in your organization

  • Execute bulk operations and automated tasks

  • Synchronize data between Atlassian and the app's database

  • Monitor license usage and optimize costs

Prerequisites

Before configuring an Organization API Key:

  • You must be an Organization Admin in your Atlassian Cloud environment

  • Access to admin.atlassian.com

  • Understanding of your organization's security policies regarding API key management

Creating and Adding an API Key

Step 1: Create the API Key in Atlassian

  1. Navigate to https://admin.atlassian.com

  2. Select your organization if you have more than one

  3. Go to Settings → API keys

  4. Click Create API key and choose API keys without scopes

  5. Provide a descriptive name for the key (e.g., "User Management & License Optimizer")

  6. Set an appropriate expiry date

Admin.atlassian Create API Key.webp

Important: When the API key expires, the app does not work anymore. Plan for key renewal well in advance.

Step 2: Add the API Key to User Manager

  1. In User Management & License Optimizer, you'll see a welcome screen stating "You must add an API Key for this app to work"

  2. Click Add a new Key

  3. In the modal that appears:

    • Paste your API key into the API Key field

    • Set the Choose Expiry Date to match the expiry date you configured in Atlassian

    • Click Check API Key to validate the key

Settings Add New Key.webp

Step 3: Validate and Save

  1. If the API key is valid, you'll see "API key is valid!" confirmation

  2. The app will automatically detect and display your organization name

  3. Click Save Key to finalize the configuration

Managing Your API Key

Viewing Current Status

Once configured, the Organization API Key section displays:

  • Organization name (automatically detected from the API key)

  • Status indicator: "Valid API Key - A valid API key has been saved"

  • Expiration warning: Shows days remaining until expiry (e.g., "Expires in 31 days")

  • Delete option: Trash icon to remove the current key

Key Expiration Management

The app monitors your API key expiration and provides multiple warning mechanisms:

Expiration Indicators

  • Visual warning: Orange warning icon appears when expiry approaches

  • Days countdown: Shows exact number of days until expiration

  • Webhook notifications: Automatically triggers 7 days before expiry (when configured)

Renewal Process

To renew an expiring API key:

  1. Create a new API key in admin.atlassian.com following the same process

  2. Return to User Management & License Optimizer settings

  3. Delete the existing key using the trash icon

  4. Add the new API key following the setup process

Security Considerations

Access Control Impact

When you configure an API key:

  • Only Organization Admins can initially access the app

  • Additional admin roles can be granted access via App Access Control settings

  • If the API key becomes invalid or is removed, only Organization Admins can configure a new key

Key Protection

  • Never share API keys outside your organization

  • Use descriptive names when creating keys to identify their purpose

  • Set appropriate expiry dates based on your security policies

  • Monitor key usage through Atlassian's admin interface

Integration with Other Features

Webhook Notifications

The API key expiry date integrates with Atlassian Automation Webhooks to provide automated alerts:

  • 7-day warning: Automatically triggers webhook when key expires in 7 days

  • Custom automation: Create Jira issues, send emails, or post to Slack/Teams

  • Proactive management: Ensures you never experience service interruption

App Access Control

The API key enables the App Access Control functionality:

  • Default access: Only Organization Admins can use the app

  • Extended access: Grant usage to Product Admins and User Access Admins

  • Security boundary: These roles gain full organization-wide access within the app

Data Synchronization

A valid API key is required for all synchronization operations:

  • Initial sync: Complete data import when first configured

  • Scheduled sync: Daily synchronization at configured time

  • Manual sync: On-demand data refresh

  • Pre-operation sync: Automatic sync before bulk operations

Troubleshooting

Common Issues

"API key is invalid" Error

Possible causes:

  • Key was deleted or expired in Atlassian admin

  • Incorrect key pasted (extra spaces, missing characters)

  • Organization permissions changed

Solutions:

  1. Verify the key exists in admin.atlassian.com

  2. Check the key hasn't expired

  3. Ensure you have Organization Admin permissions

  4. Create a new key if necessary

App Stopped Working Suddenly

Most likely cause: API key expired

Solutions:

  1. Check the expiry date in settings

  2. Create a new API key in Atlassian admin

  3. Update the key in User Management & License Optimizer

Cannot Access Settings

Cause: Only Organization Admins can manage API keys

Solution: Contact your Organization Admin to:

  • Configure the initial API key

  • Grant you access via App Access Control settings

Best Practices

Key Management

  • Document key details: Keep records of when keys were created and their purpose

  • Set calendar reminders: Schedule renewals well before expiry

  • Use meaningful names: Include "User Management" in the key name for easy identification

  • Plan for coverage: Ensure multiple Organization Admins can manage keys

Security

  • Regular rotation: Consider rotating keys annually for security

  • Monitor usage: Review key activity in Atlassian admin logs

  • Immediate action: Replace keys immediately if compromised

  • Principle of least privilege: Only grant additional admin access when necessary

Operational Excellence

  • Configure webhooks: Set up automated expiry notifications

  • Test renewals: Practice the renewal process in non-production environments

  • Document procedures: Maintain runbooks for key management

  • Monitor health: Regularly check the app status and key validity