Scoped API keys in Atlassian Cloud administration let you restrict exactly what each API key can do – read, write, or delete – replacing the risky all-or-nothing approach of traditional API keys. In our walkthrough, we demonstrate how to create scoped API keys step by step, set expiration dates, and manage existing keys to follow the principle of least privilege, significantly reducing your organization’s attack surface.
This feature is a major security upgrade for any organization using API keys to automate tasks or integrate with external tools in Atlassian Cloud.
In our video, we walk through the entire process of creating and managing scoped API keys in Atlassian administration:
The Problem with Traditional API Keys
In the past, an organization API key in Atlassian was essentially all or nothing. Once created, it could be used to read, write, and delete data across your entire organization. This represents a large attack surface. If a key leaks, an attacker can do significant damage – accessing sensitive data, modifying configurations, or even deleting critical resources. There was no way to limit what an API key was authorized to do, which made every key a potential security liability.
This approach is fundamentally at odds with modern security best practices, which emphasize granting only the minimum permissions necessary for a task to function. Organizations relying on integrations and automation tools were forced to accept this risk, or avoid using API keys altogether.
What Are Scoped API Keys?
Scoped API keys fix this problem by letting you define exactly which actions a key can perform. Instead of granting full access, you can limit a key to read-only, write, or delete permissions – or any combination of specific scopes you choose. This means that even if a key is compromised, the damage an attacker can cause is strictly limited to the permissions assigned to that key.
This aligns with the principle of least privilege, a foundational concept in cybersecurity that states users and systems should only have the minimum level of access required to perform their functions. Scoped API keys bring this principle directly into your Atlassian Cloud integrations.
How to Create a Scoped API Key
Creating a scoped API key is straightforward. Here is the step-by-step process we demonstrate in our video:
Step 1: Navigate to API Keys
Start in Atlassian administration by going to Organization Settings and then API Keys. Here you will see an overview of all previously created API keys, including their scope, usage status, and expiration dates.
Step 2: Create a New API Key
Click the Create API Key button. You will be presented with two options: creating an API key without scopes (which is not recommended) or creating an API key with scopes. Always choose the scoped option for better security.
Step 3: Name and Set Expiration
Give your API key a descriptive name that reflects its purpose – for example, “read only demo.” You should also set an expiration date. Setting an expiration is recommended as it ensures keys don’t remain active indefinitely, further reducing your security risk.
Step 4: Select Key Scopes
This is where the real power of scoped API keys comes in. You will see a table listing all available scopes. You can adjust the results per page to see all options at once – for example, changing it to show 14 results per page. You can search for specific scopes or use the scope action filter to narrow down by read, write, or delete actions. For a read-only key, filter by read-only and then select all relevant read scopes, or choose only the specific scopes your integration needs.
Step 5: Review and Create
Before finalizing, you will see a review screen summarizing the API key you are about to create, including its name, expiration, and all selected scopes. Verify everything is correct, then click Create API Key.
Step 6: Save Your API Key Immediately
This is the most critical step. Once the API key is generated, you must copy it and store it in a secure location such as a password manager. You will not be able to view this key again after leaving this page. If you fail to copy it, there is no way to retrieve it later – you would need to create a new key entirely.
Managing and Reviewing Existing API Keys
After creation, your new scoped API key appears in the API key list within Atlassian administration. The list shows important details for each key:
- Who created the key
- How many scopes are assigned
- Whether the key has been used
- The expiration date
This overview makes it easy to audit your organization’s API keys at a glance and identify any keys that may need attention, such as keys that are expiring soon or keys that have never been used and may be unnecessary.
Rotating Old API Keys
For existing API keys that don’t have scopes assigned, Atlassian recommends rotating them to new scoped keys. This means creating a new scoped key with the appropriate permissions, updating your integrations to use the new key, and then revoking the old unscoped key. This process ensures all active keys in your organization follow the principle of least privilege.
Failing to rotate old keys means those keys continue to have unrestricted access to your organization’s data, leaving you vulnerable to the same security risks that existed before scoped API keys were introduced.
Why Scoped API Keys Matter for Your Organization
Implementing scoped API keys provides several critical benefits for organizations using Atlassian Cloud:
- Stronger security for all integrations and automated workflows
- Reduced risk of data breaches if a key is compromised
- Better control over what automation tools can access and modify
- Cleaner and more compliant admin workflows that align with security policies
By deciding whether a key can only read, also write, or additionally delete, you keep your organization much safer. The granularity of scoped API keys means you no longer have to accept unnecessary risk just to enable integrations.
Getting Started
To begin using scoped API keys, head to admin.atlassian.com, navigate to Organization Settings, and then API Keys. From there, you can create new scoped keys and review your existing keys to determine which ones need to be rotated. Make it a practice to always assign the minimum required scopes and set expiration dates on every key you create.
