> ## 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 Confluence Cloud using an Atlassian API Token

export const platform_1 = "Confluence"

export const limit_0 = "rate limits apply; implement backoff for 429 errors"

export const platform_0 = "Confluence"

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**      | e.g., `https://your-company.atlassian.net` |
    </Card>

    ## Overview

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

    ## Prerequisites

    <Steps>
      <Step title="Administrator Access">
        You need **Confluence Administrator** or **Space Administrator** role to access comprehensive data.
      </Step>

      <Step title="Required Permissions">
        | Access Level                 | Required For                        |
        | ---------------------------- | ----------------------------------- |
        | **Space Administrator**      | Full space access, user activity    |
        | **Confluence Administrator** | All spaces, comprehensive user data |
        | **View permission**          | Reading pages in specific spaces    |
      </Step>
    </Steps>

    ## Setup Guide

    <Steps>
      <Step title="Generate API Token">
        1. Visit <a href="https://id.atlassian.com/manage-profile/security/api-tokens" target="_blank" rel="noopener noreferrer">Atlassian API Tokens</a>
        2. Click **Create API token**
        3. Label it: `Parable Confluence Integration`
        4. Set an appropriate expiration date
        5. 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="Gather Instance Details">
        | Field        | Where to Find It                                  |
        | ------------ | ------------------------------------------------- |
        | Instance URL | Browser address bar: `your-company.atlassian.net` |
        | Your Email   | The email you sign in with                        |
      </Step>

      <Step title="Enter values in the form">
        1. Enter **Email**, **API Token**, and **Base URL** 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/wiki/api/v2/users?limit=1" \
        -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/wiki/api/v2/users?limit=1",
          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>

    ## API Endpoints Reference

    ### Users

    ```
    GET /wiki/api/v2/users
    ```

    Parameters: `start`, `limit` (max 100), `accountId`

    ### Pages

    ```
    GET /wiki/api/v2/pages
    ```

    Parameters: `start`, `limit`, `spaceKey`, `expand` (body, version, space, history)

    <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      | Check email and API token        |
    | **403 Forbidden**         | Insufficient permissions | Verify user has admin privileges |
    | **429 Too Many Requests** | Rate limit exceeded      | Implement exponential backoff    |

    <Accordion title="Permission Errors">
      If you encounter permission errors:

      1. Verify the user has appropriate space permissions
      2. For user data access, ensure the user has admin privileges
      3. For activity data, confirm the user has Confluence Administrator role
    </Accordion>

    ## Additional Resources

    <CardGroup cols={2}>
      <Card title="Confluence REST API v2" icon="book" href="https://developer.atlassian.com/cloud/confluence/rest/v2/intro/">
        Official API documentation
      </Card>
    </CardGroup>
  </Tab>
</Tabs>