Atlassian Jira API Authentication: Methods & Best Practices (2026)

Authentication overview

Authentication for the Atlassian Jira API is a foundational security measure, ensuring that only authorized applications and users can access and manipulate Jira resources. The Jira Cloud platform provides several authentication mechanisms tailored to different integration scenarios, from third-party applications to personal scripts and automated workflows. Selecting the appropriate method depends on the application's nature, the level of user interaction required, and the desired security posture. All interactions with the Jira API require secure communication over HTTPS to protect credentials and data in transit.

The core principle behind Jira API authentication is to verify the identity of the requesting entity and grant permissions based on that identity. This process typically involves exchanging credentials for an access token or directly using credentials in a request header. Atlassian strongly recommends using OAuth 2.0 for applications that interact with multiple users or require specific permissions, while API tokens are suitable for automated scripts or integrations operating on behalf of a single user. Understanding the distinctions between these methods is crucial for building secure and scalable integrations with Jira Cloud.

Supported authentication methods

The Atlassian Jira Cloud API supports several authentication methods, each designed for specific use cases and offering varying levels of security and control. Developers should choose the method that best aligns with their application's architecture and security requirements.

OAuth 2.0 (3-legged and 2-legged)

OAuth 2.0 is the recommended authentication method for most third-party applications integrating with Jira Cloud. It provides a secure and standardized way for applications to obtain delegated access to user data without ever handling user credentials directly. The OAuth 2.0 framework defines different grant types, two of which are particularly relevant for Jira:

• 3-legged OAuth (3LO): This flow is used when an application needs to access Jira resources on behalf of an end-user. The user grants permission to the application, and the application receives an access token that allows it to make API calls within the scope of the granted permissions. This is ideal for web applications, mobile apps, and other integrations where user consent is required. For detailed steps, refer to the Atlassian documentation on 3-legged OAuth. OAuth 2.0 is an industry-standard protocol for authorization, as described by the OAuth 2.0 specification.
• 2-legged OAuth (2LO): This flow is used for applications that need to access Jira resources on their own behalf, without a specific user context. It's often employed for service-to-service integrations or applications that automate tasks across an organization. The application authenticates itself using its own credentials (client ID and client secret) to obtain an access token.

API Tokens

API tokens are an alternative to password-based authentication for scripts, bots, and other automated tools accessing Jira Cloud. Instead of using a user's Atlassian account password, an API token is a long, randomly generated string that acts as a secure substitute. API tokens are associated with a specific user and inherit that user's permissions. This method is simpler to implement than OAuth 2.0 for personal scripts or internal integrations where a single user's permissions are sufficient.

Basic Authentication (Username and API Token)

While historically, Jira Cloud supported Basic Authentication with a username and password, Atlassian has deprecated the use of passwords for Basic Auth in favor of API tokens. For new integrations and existing ones, it is critical to use an API token in place of the password when performing Basic Authentication. This provides enhanced security by preventing the exposure of actual user passwords. The format for Basic Auth with an API token involves encoding the email address and API token as a Base64 string and including it in the Authorization header.

Table of Authentication Methods

Getting your credentials

The process for obtaining credentials varies depending on the chosen authentication method:

For OAuth 2.0 (3LO and 2LO)

1. Register an App: Navigate to the Atlassian Developer Console. Create a new app and configure its details, including the necessary permissions (scopes) and callback URLs (for 3LO).
2. Obtain Client ID and Secret: Upon successful app registration, the Developer Console will provide a Client ID and Client Secret. These are your application's unique identifiers and credentials. Keep the Client Secret confidential.
3. Implement the OAuth Flow: Follow the specific OAuth 2.0 flow (3LO or 2LO) to exchange an authorization code for an access token and, for 3LO, a refresh token. The access token is used to make API calls.

For API Tokens

1. Log in to Atlassian Account: Log in to your Atlassian account at id.atlassian.com/manage-profile/security/api-tokens.
2. Create an API Token: Click "Create API token," provide a label for your token (e.g., "My Jira Integration"), and then click "Create."
3. Copy the Token: The generated API token will be displayed once. Copy it immediately, as it will not be shown again. Store this token securely.
4. Use in Basic Auth: When using Basic Authentication, your username will be your Atlassian account email, and your password will be the generated API token.

Authenticated request example

Here's an example of an authenticated request using an API token with Basic Authentication in cURL. Replace YOUR_EMAIL, YOUR_API_TOKEN, and YOUR_JIRA_CLOUD_URL with your actual credentials and Jira instance URL.

curl --request GET \
  --url 'https://YOUR_JIRA_CLOUD_URL.atlassian.net/rest/api/3/myself' \
  --user 'YOUR_EMAIL:YOUR_API_TOKEN' \
  --header 'Accept: application/json'

This cURL command fetches information about the currently authenticated user (myself endpoint). The --user flag handles the Base64 encoding of the email and API token automatically for Basic Authentication. For OAuth 2.0, the Authorization header would typically be Bearer YOUR_ACCESS_TOKEN.

Security best practices

Adhering to security best practices is essential when integrating with the Atlassian Jira API to protect sensitive data and maintain system integrity:

• Use OAuth 2.0 for Third-Party Applications: For applications that will be used by multiple users or require access to a broad range of Jira data, OAuth 2.0 (specifically 3-legged OAuth) is the most secure method. It avoids storing user credentials and allows for fine-grained permission control through scopes.
• Protect API Tokens: Treat API tokens with the same level of security as passwords. Do not hardcode them directly into source code. Instead, use environment variables, secure configuration files, or secret management services. Rotate API tokens regularly and revoke them immediately if compromised.
• Scope Permissions Minimally: When configuring OAuth 2.0 applications or considering the permissions of the user associated with an API token, always request or grant only the minimum necessary permissions (scopes) required for your integration to function. This principle of least privilege reduces the impact of a potential security breach.
• Secure Your Callback URLs (for OAuth 3LO): Ensure that your OAuth 3LO application's callback URLs are registered correctly and are protected. Only allow redirects to trusted and secure (HTTPS) endpoints to prevent authorization code interception attacks.
• Encrypt Data in Transit (HTTPS): All communications with the Jira API must occur over HTTPS. This encrypts data exchanged between your application and Jira, protecting credentials and sensitive information from eavesdropping. Atlassian enforces HTTPS for all API endpoints.
• Implement Robust Error Handling and Logging: Implement secure error handling that avoids exposing sensitive information in error messages. Log authentication attempts and failures to monitor for suspicious activity and aid in incident response.
• Regularly Review Access: Periodically review the access granted to your applications and API tokens. Remove access for integrations that are no longer in use.
• Avoid Storing Sensitive Data Unnecessarily: Only store the Jira data absolutely necessary for your application's functionality. If sensitive data must be stored, ensure it is encrypted at rest.
• Stay Updated: Keep your application dependencies and frameworks updated to benefit from the latest security patches. Monitor Atlassian's developer documentation for any security advisories or changes to authentication protocols. For example, the Atlassian Jira Platform documentation is regularly updated with best practices.