Atlassian API Tokens Security Guide: Scoped Tokens, Expiry and Admin Controls

An Atlassian API token lets a script act as a person in Jira, Confluence and Bitbucket Cloud with nothing more than an email address and a string, and it bypasses the two-step verification and SSO that protect that person's interactive login. Jira and Confluence hold source of truth for projects, incidents, architecture diagrams and, too often, pasted credentials, so a token that reads them is a high-value target for infostealers and insiders. This guide explains the credential types Atlassian Cloud offers (classic and scoped user tokens, service account tokens and OAuth 2.0 client credentials), the expiry rules, the admin controls in Atlassian Administration and Atlassian Guard, and how to detect and respond to misuse. It is for Atlassian organisation admins and security engineers, and it goes deeper on tokens than the Atlassian Cloud Security Guide.

Key takeaways

• Every token now expires. New tokens last 1 to 365 days (default one year), and tokens created before 15 December 2024 expired between 14 March and 12 May 2026, so scripts must be built for renewal.
• Prefer scoped tokens. A classic token carries the user's full access across products; a scoped token is bound to one app and named scopes such as read:jira-work.
• Automation belongs to service accounts. Service accounts have no password, are created by organisation admins, and can hold scoped API tokens or OAuth 2.0 client credentials that issue 60-minute access tokens.
• Visibility needs Guard. The central API token activity view and admin revocation of user tokens require Atlassian Guard Standard on Atlassian Cloud.
• Tokens outlive passwords. A token keeps working after a password reset until it is revoked or expires, so revocation must be part of every account compromise response.

How identity and access work in Atlassian Cloud

People sign in to an Atlassian account, usually through SSO with an identity provider for managed accounts on verified domains. Product permissions (Jira project roles, Confluence space permissions, Bitbucket workspace access) then decide what that account can see. API tokens sit beside interactive login: they are used with HTTP basic authentication (account email as the username, the token as the password) or, for scoped and service account tokens, against the platform gateway at https://api.atlassian.com/ex/jira/{cloudId} or /ex/confluence/{cloudId}. A scope never overrides product permissions: a token cannot reach data its account cannot already see.

• Token creation is user-only: nobody can create a user API token on another person's behalf. That keeps admins out of personal credentials, but it also means the organisation cannot set the token's scope or expiry for the user; it can only see, block for external users, and revoke.
• Step-up for token management: users who sign in with a password or third-party account must verify with an emailed one-time passcode before creating, managing or revoking tokens, and again after 30 minutes of inactivity. SSO and service account logins skip this step, so the strength of your identity provider is what protects token creation.
• Two-step verification does not apply to tokens: Atlassian states that users with two-step verification must use an API token for scripts. The token is effectively a second password that skips the second factor. See the API Keys vs OAuth Tokens Guide.
• Token length varies: scripts and secret scanners should not assume a fixed token length.

Admin roles and privileged access

The organisation admin role controls everything in this guide: service accounts, their credentials, the API token activity view, external user policies and audit logs. Product-level administration (for example Jira administrators, who can change schemes and workflows) is a separate layer. Treat both as privileged, and remember that a token created by an admin carries admin reach through the API.

• Keep organisation admins few: Guard Detect raises "Organization admin changes" as a detection, which tells you how Atlassian views the role. Use named admin accounts protected by the identity provider and phishing-resistant MFA. See the Privileged Access Management Guide.
• Admin API keys are a separate credential: organisation admin API keys are distinct from user API tokens, and Guard Detect has a dedicated "Admin API key creation" detection. Inventory them alongside user and service account tokens.
• External users: API token access for external users (accounts outside your verified domains) is allowed by default. Blocking it stops those users calling app APIs with a token even if they have used one before; they see a message that an admin blocked the token.

Integrations, API tokens and service accounts

Scoped tokens and scope selection

Scoped tokens bind a token to one app and a set of scopes. Atlassian recommends them over classic tokens and suggests classic tokens only where an app does not support scoped tokens. For Jira, the classic OAuth scopes show the blast radius of each choice:

Granular scopes (for example read:issue:jira) give finer control where available. Service account token scopes cannot be changed after creation, so a scope change means issuing a new token and retiring the old one.

Choosing a credential

• Service account properties: no password and no interactive login, cannot be provisioned from an identity provider, email address fixed at creation, product access assigned per app and through groups. Service accounts with Jira or Confluence access do not count toward the user limit. Deleting a service account deletes its credentials. See the Service Account Security Guide.
• Revocation delay: revoking a service account API token can take up to 10 minutes to take effect, which matters during incident containment.
• Storage: Atlassian says to save tokens in a password manager because they cannot be retrieved later. For automation, use a secrets manager and inject at runtime. See the Secrets Management Guide.
• Size matters: a small team on the free tier gets 5 service accounts and no central view of user tokens, so it must rely on short expiry and a manual inventory. A large organisation should buy the Guard visibility before it scales automation.

Logging and detection

• API token activity: shows active tokens per managed account with created, expiry and last used dates. Review it monthly for tokens held by leavers or by people who left a project, which Atlassian calls out as a leak assessment use.
• Service account view: Directory, Service accounts, View API tokens shows the same fields for service account tokens.
• Guard Detect: relevant detections include "Admin API key creation", "Organization admin changes", "Policy changes" (IP allowlist, authentication policies, verified domains) and "Exporting data" (Confluence page and space exports, site backups, audit log exports). Detections can be sent to a SIEM, and audit log activities can be forwarded with webhooks.
• Behavioural signals: bulk issue searches, attachment downloads and Confluence exports from a single account outside working hours are the pattern of token-driven collection, which ATT&CK tracks as T1213 Data from Information Repositories and T1213.001 Confluence. Stolen tokens map to T1528 Steal Application Access Token and tokens found in files to T1552.001 Credentials In Files. See the Infostealer Threat Guide.

Metrics:

1. Share of active tokens that are scoped or service account credentials rather than classic user tokens.
2. Number of tokens with expiry over 90 days, trending down.
3. Tokens not used in 60 days (revoke candidates).
4. Tokens held by deactivated or departed users (target zero).
5. Number of organisation admins and admin API keys.
6. Time from compromise report to token revocation.

Hardening baseline

1. Get the inventory: with Guard Standard, export the API token activity view; without it, ask product owners to list scripts and integrations. Record owner, purpose, scopes and expiry for each token.
2. Set expectations on expiry: publish a standard such as 90 days maximum for user tokens and the shortest workable period for service account tokens. The admin controls documented by Atlassian do not set a shorter maximum for user tokens, so enforce your standard through review and revocation.
3. Pilot service accounts: move one high-volume integration to a service account with OAuth 2.0 client credentials, run it in parallel with the old token, confirm the new requests in logs, then revoke the old token.
4. Convert classic to scoped: for each remaining classic token, create a scoped replacement, switch the base URL to api.atlassian.com with the Cloud ID (not the organisation ID), test, then revoke the classic token. Rollback is creating a fresh token, since revoked tokens are permanently deleted.
5. Block external user token access unless a documented partner integration needs it, starting with the Test policy.
6. Enforce SSO and MFA for managed accounts so token creation sits behind your identity provider, and tie offboarding to token revocation using the Delete API token API.
7. Turn on detections for admin API key creation, admin changes, policy changes and data export, routed to the security team.

Common misconfigurations

• Scripts on personal accounts: a token on an employee's account dies with the employee or, worse, the account is kept alive to keep the script running. That is the OWASP NHI10 Human Use of NHI Guide problem in reverse: an NHI running on a human identity.
• Credentials on unmanaged endpoints: in the Schneider Electric Jira Breach, the attacker said exposed credentials gave access to Jira, and researchers linked them to an infostealer-infected employee machine that also held Jira migration account credentials. Tokens and passwords cached on developer laptops need the same protection as production secrets.
• Year-long tokens by default: accepting the one-year default for every token, then being surprised by a mass expiry that breaks integrations, as many teams found in the March to May 2026 expiry window.
• Revoking passwords but not tokens: resetting a compromised user's password leaves their tokens working. Use Revoke all API tokens or admin revocation as part of the response. See the OAuth Token Theft Incident Playbook.
• Over-broad scopes for convenience: granting manage:jira-configuration or write scopes to a reporting job. Pair this with the OWASP NHI5 Overprivileged NHI Guide.
• Secrets inside tickets and pages: Jira and Confluence content often contains pasted keys, which a read token can harvest. Scan both products for secrets and rotate what you find.

Framework mapping

In CIS Controls v8.1 the work maps to Control 5 Account Management and Control 6 Access Control Management.

Practitioner checklist

• Export the API token activity view and list every token with owner, scopes, expiry and last used date.
• Move scheduled automation to service accounts using OAuth 2.0 client credentials where the target supports it.
• Replace classic tokens with scoped tokens, switching to api.atlassian.com and the Cloud ID.
• Set a maximum token expiry standard and revoke tokens that exceed it at review.
• Block API token access for external users unless a named integration requires it.
• Add token revocation (Revoke all API tokens or the Delete API token API) to offboarding and account compromise runbooks.
• Keep organisation admins to a small named group and inventory admin API keys.
• Enable Guard Detect detections for admin API key creation, admin changes, policy changes and data export, sent to your SIEM.
• Scan Jira and Confluence content for pasted secrets and rotate them.

Standards and references

• Atlassian: Manage API tokens for your Atlassian account
• Atlassian: Manage API tokens for service accounts
• Atlassian: Create OAuth 2.0 credential for service accounts
• Atlassian: Understand service accounts
• Atlassian: Understand user API tokens
• Atlassian: Block user API token access
• Atlassian Developer: Jira scopes for OAuth 2.0 (3LO) and Forge apps
• Atlassian: What events are detected (Guard Detect)

Related NHI Mgmt Group resources: Atlassian Cloud Security Guide · SaaS API Token Security Guide · Token Lifetime Policy Design Guide · Datadog API and Application Keys Security Guide