Jira REST API Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating with Jira Cloud via its REST API involves a series of foundational steps. This guide focuses on establishing connectivity, covering account creation, API token generation, and the execution of a basic authenticated request. The Jira REST API provides programmatic access to core Jira functionalities, enabling tasks such as creating issues, managing projects, and retrieving data programmatically Jira Cloud platform REST API documentation.

Before making your first API call, you will need an active Jira Cloud instance and appropriate administrative permissions to generate API tokens. The process outlined below is designed for developers seeking to quickly establish a working connection to a Jira instance.

Here is a quick reference for the steps involved:

Create an account and get keys

To access the Jira REST API, you need a Jira Cloud account. If you do not have one, Atlassian offers a free tier for up to 10 users, which is suitable for development and testing purposes Jira pricing information. Once you have an account, the primary method for authenticating REST API requests for personal scripts and integrations is using an API token in conjunction with your Atlassian account email.

1. Set up your Jira Cloud instance

If you do not already have a Jira Cloud site, you can create one by visiting the Jira free trial signup page. Follow the prompts to set up your site, which will typically have a URL in the format your-domain.atlassian.net. This domain is crucial for constructing your API request URLs.

2. Generate an API token

API tokens serve as secure, revocable passwords for programmatic access. To generate one:

1. Log in to your Atlassian account.
2. Navigate to your Atlassian API tokens page.
3. Click Create API token.
4. Give your token a descriptive label (e.g., "My Jira Integration").
5. Click Create.
6. Copy the generated token immediately. It will not be shown again. Store this token securely, as it grants access to your Jira data. Treat it like a password.

You will use this token along with your Atlassian account email address for Basic authentication. The email address used to log in to your Atlassian account is the one required for API calls, not necessarily the email associated with a specific Jira user profile if they differ.

Your first request

After obtaining your API token and identifying your Jira Cloud instance URL, you can make your first authenticated request. This example demonstrates fetching a list of projects visible to your authenticated user.

Prerequisites

• Your Atlassian account email address.
• Your generated API token.
• Your Jira Cloud instance URL (e.g., https://your-domain.atlassian.net).
• A tool to make HTTP requests (e.g., cURL, Postman, or a programming language's HTTP client).

Constructing the request

The Jira REST API uses Basic authentication for API tokens. This involves encoding your email address and API token into a Base64 string. The format is echo -n '[email protected]:YOUR_API_TOKEN' | base64.

Let's use an example to get a list of all projects. The endpoint for this is /rest/api/3/project/search Jira Projects API endpoint documentation.

Example using cURL

Replace [email protected], YOUR_API_TOKEN, and your-domain with your actual credentials and domain.

curl --request GET \
  --url 'https://your-domain.atlassian.net/rest/api/3/project/search' \
  --user '[email protected]:YOUR_API_TOKEN' \
  --header 'Accept: application/json'

In this cURL command:

• --request GET specifies the HTTP method.
• --url is the full endpoint URL.
• --user '[email protected]:YOUR_API_TOKEN' provides the Basic authentication credentials. cURL automatically Base64-encodes this.
• --header 'Accept: application/json' indicates that you prefer a JSON response.

Example using Python

A Python example illustrates how to perform the same request programmatically:

import requests
from requests.auth import HTTPBasicAuth
import json

# Replace with your actual credentials and domain
JIRA_EMAIL = "[email protected]"
JIRA_API_TOKEN = "YOUR_API_TOKEN"
JIRA_DOMAIN = "your-domain.atlassian.net"

url = f"https://{JIRA_DOMAIN}/rest/api/3/project/search"

auth = HTTPBasicAuth(JIRA_EMAIL, JIRA_API_TOKEN)

headers = {
  "Accept": "application/json"
}

response = requests.request(
   "GET",
   url,
   headers=headers,
   auth=auth
)

if response.status_code == 200:
    print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(',', ': ')))
else:
    print(f"Error: {response.status_code} - {response.text}")

This Python script uses the requests library for simplicity, which handles the Base64 encoding of credentials automatically when using HTTPBasicAuth.

Common next steps

Once you have successfully made your first API call, you can explore further functionalities:

• Explore other endpoints: Refer to the Jira REST API v3 reference to discover endpoints for issues, users, workflows, and more.
• Create and update issues: Learn how to programmatically create new issues or modify existing ones using POST and PUT requests.
• Webhooks: Set up webhooks to receive real-time notifications about events in Jira, such as issue updates or comments. This allows for proactive integrations rather than constant polling Jira webhooks documentation.
• OAuth 2.0: For third-party applications or integrations that require user consent and do not store user credentials directly, consider implementing OAuth 2.0 for authentication OAuth 2.0 specification. This is typically more complex to set up but offers enhanced security and user control.
• Jira Query Language (JQL): Utilize JQL within your API calls to perform powerful searches and filter results efficiently Jira JQL API documentation.
• Official SDKs: For more complex applications, consider using one of the Atlassian-provided or community-maintained SDKs for Java, Python, JavaScript, or other languages to streamline development.

Troubleshooting the first call

Encountering issues with your initial API call is common. Here are some troubleshooting tips:

• Check your credentials: Double-check your Atlassian account email and API token for typos. Ensure the API token has not expired or been revoked. If in doubt, generate a new token.
• Base64 encoding: If manually encoding for Basic authentication, ensure the string [email protected]:YOUR_API_TOKEN is correctly Base64 encoded without any extra spaces or newlines. Tools like MDN Web Docs on Base64 can help verify encoding.
• Incorrect URL: Verify that your Jira Cloud instance URL is correct and the API path (e.g., /rest/api/3/project/search) is appended properly.
• Permissions: The Atlassian account associated with the API token must have the necessary permissions to access the requested resources. For example, to list projects, the user needs "Browse Projects" permission for those projects. Check your Jira instance's user permissions.
• Rate limits: While unlikely for a first call, be aware that Jira Cloud APIs have rate limits. If you're rapidly testing, you might hit them.
• HTTP Status Codes:
  • 401 Unauthorized: Indicates an issue with your authentication credentials (email or API token).
  • 403 Forbidden: Your credentials are valid, but the user lacks permission to access the requested resource.
  • 404 Not Found: The URL or resource path is incorrect.
  • 5xx Server Error: An issue on Jira's side. Check the Jira REST API response codes documentation for more details.
• API token scope: Ensure the API token was created under the correct Atlassian account that has access to the Jira instance you're targeting.