Jira REST API Authentication: Methods, Setup, and Security

Authentication overview

Authentication for the Jira REST API ensures that only authorized users and applications can access and manipulate Jira Cloud data. The choice of authentication method depends on the integration's nature, whether it's a personal script, a server-side application, or a public-facing third-party service. Each method offers different levels of security, user experience, and complexity in implementation. Adhering to secure authentication practices is critical for protecting sensitive project data and maintaining the integrity of Jira instances.

The Jira REST API supports several authentication mechanisms, each designed for specific use cases. Understanding the strengths and limitations of each method is key to building secure and reliable integrations. For all methods, communication with the Jira REST API must occur over HTTPS to protect credentials and data in transit, as recommended by web security standards for API interactions.

Supported authentication methods

The Jira REST API offers distinct authentication methods to accommodate various integration scenarios. Selecting the appropriate method involves considering factors such as the application's audience, its deployment environment, and the required level of user interaction.

API Tokens

API tokens are long-lived, randomly generated strings that serve as substitutes for passwords when authenticating with the Jira REST API. They are tied to a specific user account and inherit that user's permissions. This method is suitable for automated scripts, internal integrations, or command-line tools where direct user interaction for authentication is not feasible or desired. Atlassian's documentation on Jira REST API authentication details how to use API tokens.

OAuth 2.0

OAuth 2.0 is the recommended authentication method for most third-party applications integrating with Jira Cloud. It allows applications to obtain limited access to a user's Jira data without ever handling their credentials. The process involves redirecting the user to Atlassian's authorization server, where they grant permission to the application. The application then receives an access token, which it uses to make API requests. This method enhances security by isolating the user's credentials from the application and allowing granular control over permissions. The Jira Cloud platform documentation on OAuth 2.0 (3LO) apps provides comprehensive guidance.

Basic Authentication

Basic authentication uses a username and password (or email and API token for Jira Cloud) sent as a Base64-encoded string in the Authorization header of each HTTP request. While technically supported, directly using a user's password for basic authentication in Jira Cloud is strongly discouraged and has been deprecated in favor of API tokens or OAuth 2.0 for security reasons. If using basic authentication, it is imperative to use an API token as the password, not the user's actual login password, and ensure all communications are over HTTPS. For most new integrations, API tokens or OAuth 2.0 are superior choices.

Getting your credentials

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

For API Tokens

1. Log in to your Atlassian account (the one associated with your Jira Cloud instance).
2. Navigate to your profile settings.
3. Go to the 'Security' section.
4. Click 'Create and manage API tokens'.
5. Generate a new API token, providing a label for easy identification.
6. Copy the generated token immediately, as it will only be shown once.

It is crucial to store this token securely, treating it with the same care as a password.

For OAuth 2.0

Setting up OAuth 2.0 involves registering your application with Atlassian and configuring redirect URIs and scopes.

1. Go to the Atlassian Developer Console.
2. Create a new 'OAuth 2.0 (3LO)' app.
3. Provide a name and description for your application.
4. Configure the 'Permissions' (scopes) your application requires. Scopes define the specific Jira resources and actions your app can access.
5. Add your application's 'Callback URL' (redirect URI), which is where Atlassian will send the authorization code after a user grants permission.
6. Upon creation, you will receive a Client ID and a Client Secret. These are your application's credentials for initiating the OAuth flow.

The Client ID identifies your application, and the Client Secret is a confidential key used to authenticate your application with Atlassian's authorization server. Both must be kept secure.

Authenticated request example

This example demonstrates how to make an authenticated request to the Jira REST API using an API token. This method is common for scripts and server-side integrations.

Using an API Token with Basic Authentication (HTTP Header)

When using an API token, it is sent in the Authorization header using the Basic authentication scheme. The username is your Atlassian account email, and the password is the API token itself. The combined string email:API_TOKEN is then Base64 encoded.

Example using curl:

EMAIL="[email protected]"
API_TOKEN="YOUR_API_TOKEN"
JIRA_URL="https://your-domain.atlassian.net"

# Encode credentials to Base64
AUTH_STRING=$(echo -n "$EMAIL:$API_TOKEN" | base64)

curl -X GET \
  --url "${JIRA_URL}/rest/api/3/myself" \
  --header "Authorization: Basic ${AUTH_STRING}" \
  --header "Accept: application/json"

In this example, /rest/api/3/myself is an endpoint that retrieves information about the currently authenticated user. The Authorization header contains the Base64-encoded string, prefixed with Basic. Ensure your Jira domain and API token are replaced with your actual values.

Using OAuth 2.0 (Access Token)

For applications using OAuth 2.0, after successfully completing the authorization flow, your application will receive an access_token. This token is then included in the Authorization header, typically using the Bearer scheme.

Example using curl with an OAuth 2.0 access token:

ACCESS_TOKEN="YOUR_OAUTH_ACCESS_TOKEN"
JIRA_URL="https://your-domain.atlassian.net"

curl -X GET \
  --url "${JIRA_URL}/rest/api/3/myself" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

This demonstrates the use of an access token obtained through the OAuth 2.0 flow. The access token grants temporary, scoped access to the Jira API on behalf of the user who authorized your application.

Security best practices

Securing your Jira REST API integrations is paramount to protecting your data and maintaining system integrity. Implement the following best practices:

• Use HTTPS exclusively: Always ensure that all API requests are made over HTTPS. This encrypts data in transit, preventing eavesdropping and tampering. Most modern API clients and libraries enforce HTTPS by default, but it's crucial to verify.
• Store credentials securely:
  • API Tokens: Never hardcode API tokens directly into your source code. Use environment variables, secure configuration files, or secret management services (e.g., AWS Secrets Manager, Azure Key Vault, HashiCorp Vault) to store them. Restrict access to these storage locations.
  • OAuth Client Secrets: Treat your OAuth Client Secret as a highly sensitive password. Store it securely and never expose it in client-side code (e.g., JavaScript in a browser).
• Limit permissions (Least Privilege): When generating API tokens or configuring OAuth scopes, grant only the minimum necessary permissions required for your application or script to function. Avoid giving broad administrative access if only read access to specific issues is needed. Regularly review and adjust permissions as requirements change.
• Rotate credentials regularly: Periodically rotate API tokens and OAuth Client Secrets. This reduces the window of opportunity for an attacker if credentials are compromised. Establish a schedule for rotation based on your organization's security policies.
• Implement robust error handling and logging: Log authentication failures and suspicious activity to detect potential attacks. Avoid returning verbose error messages that could leak sensitive information about your authentication mechanism.
• Secure callback URLs for OAuth: For OAuth 2.0, ensure your registered callback URLs are precise and only point to locations you control. Using overly broad redirect URIs can lead to open redirect vulnerabilities.
• Validate input: Always validate and sanitize any user-supplied input before using it in API requests to prevent injection attacks and other vulnerabilities.
• Monitor API usage: Keep an eye on your application's API usage patterns. Unusual spikes or requests from unexpected locations could indicate a compromised credential or application.
• Understand token lifetimes: OAuth access tokens generally have a limited lifespan. Design your application to handle token expiration gracefully by refreshing tokens when needed, as described in the OAuth 2.0 RFC for refreshing access tokens.