> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# API Token

> Connect Parable to Jira Cloud using an Atlassian API Token

export const platform_1 = "Jira Cloud"

export const limit_0 = "varies by endpoint; typically 100-1000 requests/minute"

export const platform_0 = "Jira"

export const tokenName_0 = "API token"

<Tabs>
  <Tab title="Setup">
    <Card title="What You'll Need" icon="key">
      | Credential          | What it is                                                          |
      | ------------------- | ------------------------------------------------------------------- |
      | **API Token**       | Generated from Atlassian account settings                           |
      | **Email Address**   | Your Atlassian account email                                        |
      | **Base URL**        | Your Jira instance URL (e.g., `https://your-company.atlassian.net`) |
      | **Domain**          | Your Atlassian domain (e.g., `your-company.atlassian.net`)          |
      | **Organization ID** | Your Atlassian organization ID                                      |
    </Card>

    ## Overview

    Connect Parable to Jira Cloud. API token authentication uses Basic Auth with your Atlassian email and a generated token for secure, automated API access.

    ## Prerequisites

    <Steps>
      <Step title="User Permissions">
        The user creating the API token needs these permissions:

        * **Global permission**: [Administer Jira](https://support.atlassian.com/jira-cloud-administration/docs/manage-global-permissions/)
        * **Project permission**: [Browse Projects](https://support.atlassian.com/jira-cloud-administration/docs/manage-project-permissions/)

        <Tip>
          For full data access, use an account with **Jira Administrator** privileges.
        </Tip>
      </Step>

      <Step title="Org-Wide Settings">
        Ensure all user emails are set to **Visible** by "Anyone":

        Users configure this in their Atlassian account settings under **Profile and visibility** → **Contact**.
      </Step>
    </Steps>

    ## Setup Guide

    <Steps>
      <Step title="Access API Token Settings">
        Navigate to the <a href="https://id.atlassian.com/manage-profile/security/api-tokens" target="_blank" rel="noopener noreferrer">Atlassian API Token Management</a> page.

        Sign in with your Atlassian account credentials.
      </Step>

      <Step title="Create an API Token">
        1. Click **Create API token**
        2. Enter a meaningful label: `Parable Integration`
        3. Click **Create**

        <Warning>
          **Copy your {tokenName_0} now!**

          This is the only time it will be displayed. Store it in a secure password manager before closing this page.
        </Warning>
      </Step>

      <Step title="Find Your Organization ID">
        1. Go to [Atlassian Admin Console](https://admin.atlassian.com)
        2. Look at the URL: `https://admin.atlassian.com/o/{ORG_ID}/...`
        3. Copy the **ORG\_ID** value
      </Step>

      <Step title="Note Your Instance URL">
        Your Jira instance URL follows this pattern:

        ```
        https://your-company.atlassian.net
        ```

        Find this in your browser's address bar when viewing Jira.
      </Step>

      <Step title="Enter values in the form">
        1. Enter **Email**, **API Token**, **Base URL**, **Domain**, and **Organization ID** in the connector form.
        2. Click **Save & test connection**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Reference">
    ## Verify Your Setup

    The API uses **Basic authentication**. Combine your credentials and Base64 encode them:

    ```
    username:password  →  Base64 encode  →  Authorization: Basic {encoded}
    ```

    <CodeGroup>
      ```bash cURL theme={null}
      # The -u flag handles Base64 encoding automatically
      curl -X GET "https://your-company.atlassian.net/rest/api/3/myself" \
        -u "your-email@company.com:YOUR_API_TOKEN" \
        -H "Content-Type: application/json"
      ```

      ```python Python theme={null}
      import requests
      import base64

      # Encode credentials
      credentials = "your-email@company.com:YOUR_API_TOKEN"
      encoded = base64.b64encode(credentials.encode()).decode()

      response = requests.get(
          "https://your-company.atlassian.net/rest/api/3/myself",
          headers={
              "Authorization": f"Basic {encoded}",
              "Content-Type": "application/json"
          }
      )
      print(response.json())
      ```
    </CodeGroup>

    <Tip>
      For {platform_0}, use your **email address** as the username and the **API token** as the password.
    </Tip>

    <Check>
      **Success!** If you received a `200 OK` response with valid data, your credentials are configured correctly. You can now proceed to configure this connector in Parable.
    </Check>

    ## Permissions Reference

    | Endpoint                      | Required Permission | Data Accessed    |
    | ----------------------------- | ------------------- | ---------------- |
    | `/rest/api/3/search/jql`      | BROWSE\_PROJECTS    | Issues via JQL   |
    | `/rest/api/3/project/search`  | BROWSE\_PROJECTS    | Project list     |
    | `/rest/api/3/users`           | ADMINISTER          | User information |
    | `/rest/api/2/auditing/record` | ADMINISTER          | Audit logs       |

    <Tip>
      **Rate Limits:** {platform_1} enforces rate limits of **{limit_0}**.

      Parable handles rate limiting automatically with exponential backoff, but initial syncs of large datasets may take longer due to these limits.
    </Tip>

    ## Troubleshooting

    | Error                     | Meaning                  | Solution                                                   |
    | ------------------------- | ------------------------ | ---------------------------------------------------------- |
    | **401 Unauthorized**      | Invalid credentials      | Verify email and token are correct                         |
    | **403 Forbidden**         | Insufficient permissions | Check user has BROWSE\_PROJECTS and ADMINISTER permissions |
    | **429 Too Many Requests** | Rate limit hit           | Reduce request frequency; implement backoff                |

    <Accordion title="Common Issues">
      ### "User not found" when querying users

      Ensure the user's email visibility is set to "Anyone" in their Atlassian profile settings.

      ### Token created but not working

      Wait 5-10 minutes for the token to propagate across Atlassian's systems.
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Jira Cloud REST API" icon="book" href="https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/">
        Official API documentation
      </Card>

      <Card title="Basic Auth Guide" icon="key" href="https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/">
        Atlassian authentication guide
      </Card>
    </CardGroup>
  </Tab>
</Tabs>