Getting started overview

Integrating with JIRA involves a series of steps designed to get you from account creation to executing your first API call. This guide focuses on the JIRA Cloud platform, which typically utilizes a REST API for programmatic interaction. The process generally includes setting up an Atlassian account, establishing a JIRA Cloud site, generating an API token for authentication, and then using this token to make a basic request, such as retrieving project information or creating an issue.

JIRA's API supports various operations, from managing projects and issues to automating workflows and integrating with other development tools. For a comprehensive overview of JIRA's capabilities, consult the official Jira Cloud documentation.

Here's a quick reference table outlining the essential steps to get started:

Step What to Do Where
1. Create Account Sign up for an Atlassian account and create a JIRA Cloud site. Jira Pricing page (to select a plan, including free)
2. Generate API Token Create a personal API token for authentication. Atlassian API tokens management
3. Obtain Site URL Note your JIRA Cloud site's base URL. Your JIRA Cloud instance URL (e.g., your-site-name.atlassian.net)
4. Construct Request Formulate a basic API request (e.g., get current user). Jira Cloud REST API myself endpoint
5. Execute Request Send the request using cURL or an HTTP client. Terminal or preferred API client

Create an account and get keys

Before making any API calls, you need an Atlassian account and a JIRA Cloud site. JIRA offers a free tier for up to 10 users, which is suitable for initial development and testing.

  1. Sign up for an Atlassian account: Navigate to the Jira pricing page and choose a plan, including the free option. Follow the prompts to create your Atlassian account, which will also prompt you to create a JIRA Cloud site (e.g., your-company.atlassian.net). This site URL is crucial for all your API requests.
  2. Verify your email: Complete any necessary email verification steps to activate your account.
  3. Generate an API Token: JIRA's REST API primarily uses API tokens for authenticated requests, especially for script-based integrations or personal access. OAuth 2.0 is available for more complex application integrations requiring user consent. For this getting started guide, an API token is sufficient.
    To generate a token:
    1. Log in to your Atlassian account.
    2. Go to your Atlassian profile and select Manage your account.
    3. Navigate to the Security tab.
    4. Under API tokens, click Create and manage API tokens.
    5. Click Create API token, give it a descriptive label, and then click Create.
    6. Copy the generated token immediately. It will only be displayed once. Treat this token like a password; do not expose it in public repositories or client-side code. For detailed instructions, refer to the Atlassian API tokens management guide.
  4. Identify your JIRA Cloud site URL: Your JIRA Cloud site URL will be in the format https://your-site-name.atlassian.net. This is the base URL for all your JIRA API calls.

Your first request

With your Atlassian account, JIRA Cloud site, and API token ready, you can now make your first API call. We'll use the /rest/api/3/myself endpoint to retrieve information about the currently authenticated user. This is a simple GET request that confirms your authentication is set up correctly.

Authentication Headers

JIRA API requests using an API token require Basic Authentication. You'll encode your email address and API token into a base64 string. The format is email:API_TOKEN.

For example, if your email is [email protected] and your token is YOUR_API_TOKEN, you would encode [email protected]:YOUR_API_TOKEN.

echo -n '[email protected]:YOUR_API_TOKEN' | base64

This will output a base64 encoded string, which you will then use in the Authorization header:

Authorization: Basic <base64_encoded_string>

Making the Request with cURL

Replace <your-site-name> with your actual JIRA Cloud site name and <base64_encoded_string> with the string you generated above.

curl --request GET \
  --url 'https://<your-site-name>.atlassian.net/rest/api/3/myself' \
  --user '[email protected]:YOUR_API_TOKEN' \
  --header 'Accept: application/json'

Alternatively, using the Authorization header directly:

curl --request GET \
  --url 'https://<your-site-name>.atlassian.net/rest/api/3/myself' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic <base64_encoded_string>'

Expected Response

A successful request will return a JSON object containing details about the authenticated user, similar to this:

{
  "self": "https://your-site-name.atlassian.net/rest/api/3/user?accountId=5b10ac8d82e05b22cc7d4941",
  "accountId": "5b10ac8d82e05b22cc7d4941",
  "emailAddress": "[email protected]",
  "avatarUrls": {
    "48x48": "https://avatar-url-48x48.png",
    "24x24": "https://avatar-url-24x24.png",
    "16x16": "https://avatar-url-16x16.png",
    "32x32": "https://avatar-url-32x32.png"
  },
  "displayName": "User Name",
  "active": true,
  "timeZone": "America/Los_Angeles",
  "locale": "en_US",
  "accountType": "atlassian"
}

Common next steps

After successfully making your first authenticated call, consider these next steps to deepen your integration with JIRA:

  • Explore other API Endpoints: The Jira Cloud Platform REST API documentation provides a comprehensive list of endpoints for managing projects, issues, workflows, and more. Common operations include creating issues, updating issue fields, searching for issues using JQL (Jira Query Language), and managing users/groups.
  • Understand JQL: JQL is a powerful query language used to search for issues in JIRA. Many API endpoints accept JQL for filtering and retrieving specific sets of issues. Learn more about advanced searching with JQL.
  • Implement OAuth 2.0: For applications that interact with JIRA on behalf of multiple users or require more granular permission control, OAuth 2.0 is the recommended authentication method. Atlassian provides detailed OAuth 2.0 (3LO) documentation for building apps.
  • Utilize SDKs: While cURL is excellent for initial testing, using one of the official or community-supported SDKs (Java, JavaScript, Python, Ruby) can streamline development by abstracting HTTP requests and JSON parsing.
  • Webhooks: Set up webhooks to receive notifications in real-time when specific events occur in JIRA (e.g., an issue is created, updated, or deleted). This enables reactive integrations and automation. Consult the Jira Cloud webhooks documentation.
  • Error Handling: Implement robust error handling in your application to gracefully manage API rate limits, invalid requests, and other potential issues.
  • Security Best Practices: Always store your API tokens securely, preferably using environment variables or a secrets management system. Avoid hardcoding credentials directly into your application code. General API security principles, such as those outlined by Mozilla's HTTP authentication guide, apply here.

Troubleshooting the first call

If your first API call doesn't return the expected result, here are some common issues and troubleshooting steps:

  • HTTP 401 Unauthorized:
    • Incorrect API Token or Email: Double-check that the email address and API token used in the --user argument or Authorization header are correct and belong to a user with access to the JIRA site. Ensure there are no leading/trailing spaces.
    • Invalid Base64 Encoding: If you manually encoded, verify the base64 string is correct. The format must be email:API_TOKEN.
    • Token Permissions: Ensure the API token has the necessary permissions. The myself endpoint typically requires basic user permissions.
  • HTTP 403 Forbidden:
    • Insufficient Permissions: The user associated with the API token might not have the necessary global or project-specific permissions to access the requested resource. Check the user's permissions in your JIRA Cloud site.
    • IP Whitelisting: If your JIRA instance has IP allowlisting configured, ensure the IP address from which you are making the request is permitted.
  • HTTP 404 Not Found:
    • Incorrect Site URL: Verify that your JIRA Cloud site URL (https://<your-site-name>.atlassian.net) is accurate.
    • Incorrect Endpoint Path: Double-check the API endpoint path (e.g., /rest/api/3/myself) for typos or incorrect versioning.
  • HTTP 400 Bad Request:
    • Malformed Request Body: If you're sending a POST or PUT request, ensure the JSON body is valid and adheres to the API's schema requirements.
    • Missing Headers: Ensure you are sending the Accept: application/json and Content-Type: application/json (for requests with a body) headers.
  • Network Issues: Check your local network connectivity and any firewalls or proxies that might be blocking the request.
  • Rate Limiting: JIRA APIs have rate limits. If you're making many requests in a short period, you might encounter a 429 Too Many Requests error. Implement exponential backoff for retries.

For more detailed error codes and troubleshooting, refer to the Jira Cloud Platform REST API documentation and its specific endpoint details.