Authenticating with Jira Cloud APIs to Create and Fetch Issues

🚀 End-to-End Guide: Authenticating with Jira Cloud APIs to Create and Fetch Issues

Integrating with Jira Cloud programmatically is a common requirement for automation, testing, and DevOps workflows. This guide walks through the complete authentication flow using OAuth (client credentials) and demonstrates how to fetch and create Jira issues using REST APIs.

This approach is designed for non-interactive service integrations, meaning no UI login is required.

---

🔐 Overview of the Flow

At a high level, interacting with Jira APIs involves four key steps:

1. Generate an access token
2. Discover accessible resources (Cloud ID)
3. Fetch existing issues
4. Create new issues

Each step builds on the previous one.

---

1️⃣ Generate an Access Token

Authentication begins by exchanging your client credentials for an access token.

Pre-requisites

1. Create a service user in Atlassian Jira directory.
2. Create an OAuth 2.0 credentials to get the Client ID and Client Credentials.

Request

POST https://auth.atlassian.com/oauth/token
Content-Type: application/json

Body

{
  "grant_type": "client_credentials",
  "client_id": "{{CLIENT_ID}}",
  "client_secret": "{{CLIENT_SECRET}}",
  "audience": "api.atlassian.com"
}

This returns a response containing:

{
  "access_token": "your_token_here",
  "expires_in": 3600
}

You’ll use this access_token for all subsequent API calls.  

---

2️⃣ Retrieve Cloud ID (Accessible Resources)

Jira APIs require a Cloud ID, which identifies the Jira instance associated with your token.

Request

GET https://api.atlassian.com/oauth/token/accessible-resources
Authorization: Bearer {{ACCESS_TOKEN}}
Accept: application/json

Response

[
  {
    "id": "cloud-id",
    "url": "https://your-instance.atlassian.net"
  }
]

• id → used as cloudId
• url → base Jira site URL

This step is essential because all Jira API calls must go through the API gateway using the Cloud ID.  

---

3️⃣ Fetch a Jira Issue

Once authenticated, you can retrieve issue details.

Request

GET https://api.atlassian.com/ex/jira/{{CLOUD_ID}}/rest/api/3/issue/{{PROJECT_KEY}}-1
Authorization: Bearer {{ACCESS_TOKEN}}
Accept: application/json

What this does

• Uses the API gateway (api.atlassian.com)
• Authenticates with Bearer token
• Fetches a specific issue using its key

This endpoint returns full issue details including summary, status, and metadata.  

---

4️⃣ Create a Jira Issue

Creating issues programmatically is one of the most common use cases.

Request

POST https://api.atlassian.com/ex/jira/{{CLOUD_ID}}/rest/api/3/issue
Authorization: Bearer {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

Body

{
  "fields": {
    "project": {
      "key": "{{PROJECT_KEY}}"
    },
    "summary": "Bug created from API",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "Created via API using OAuth token"
            }
          ]
        }
      ]
    },
    "issuetype": {
      "name": "Bug"
    }
  }
}

Important Notes

• Description must use Atlassian Document Format (ADF) — plain text is not accepted.
• project.key must exist in your Jira instance.
• issuetype.name must be valid (e.g., Bug, Task, Story).

This request creates a new issue and returns its ID and key.  

---

🔁 Automating the Flow

In tools like Bruno or Postman, you can automate this workflow:

• Store access_token after token request
• Extract cloudId dynamically
• Reuse both in subsequent requests

Example script:

const body = bru.response.json();
bru.setEnvVar("ACCESS_TOKEN", body.access_token);

---

⚠️ Common Pitfalls

❌ Using the wrong base URL

• Don’t use: https://your-domain.atlassian.net/rest/api/...
• Use: https://api.atlassian.com/ex/jira/{cloudId}/...

---

❌ Missing permissions

• The service account must have:
  • Browse Projects
  • Create Issues (for POST)

---

❌ Invalid payload

• Missing required fields → 400 error
• Wrong issue type → validation failure

---

❌ Expired token

• Tokens expire (usually in 1 hour)
• Regenerate as needed

---

🧩 Putting It All Together

Here’s the complete sequence:

1. 🔑 Get access token
2. 🌐 Get Cloud ID
3. 📥 Fetch issue
4. 📤 Create issue

This workflow enables full read/write automation with Jira Cloud APIs.

---

🏁 Conclusion

Using OAuth with client credentials provides a secure and scalable way to interact with Jira Cloud APIs without relying on user login or UI access.

With just a few API calls, you can:

• integrate Jira into CI/CD pipelines
• automate bug creation
• build dashboards or monitoring tools

Once set up, this becomes a powerful foundation for any Jira-based automation.

---

Please feel free to reachout psrdotcom@gmail.com for any feedback and suggestions.