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

# Jira Cloud

Jira Cloud (OAuth) connects your organization's issues, projects, boards, and sprints to Airia agents, backed directly by Atlassian's own REST API. Each person connects with their own Atlassian account, and access follows Jira's own permissions on top of whatever scopes the connection is granted.

## What It Can Do

| Category                   | Capability                                                                                                                                                                                                |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Issues**                 | Create, read, update, delete, assign, and transition issues, individually or in bulk. Search with JQL, read changelogs, and manage comments, attachments, issue links, remote links, watchers, and votes. |
| **Worklogs**               | Log time against an issue, and read, update, or delete existing worklog entries.                                                                                                                          |
| **Projects**               | Search and read project details, and manage components and versions.                                                                                                                                      |
| **Boards and Sprints**     | Read Scrum and Kanban boards, read and create sprints, move issues into a sprint, and read the issues on a board or in a sprint.                                                                          |
| **Users**                  | Search users, look up a specific user or the current authenticated user, and find users assignable to an issue or project.                                                                                |
| **Reference Data**         | Read labels, priorities, statuses, issue types, fields, and field options.                                                                                                                                |
| **Filters and Dashboards** | Create, read, update, and delete saved JQL filters, and read dashboards.                                                                                                                                  |

See [Tools and Required Scopes](#tools-and-required-scopes) below for the full list of tools behind these capabilities.

## Connecting

<Steps>
  <Step title="Register an OAuth app">
    Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and select **Create** → **OAuth 2.0 integration**. Give the app a name, for example "Airia Jira," and save.
  </Step>

  <Step title="Add the callback URL">
    Select **Authorization** in the left sidebar, then click **Add** next to OAuth 2.0 (3LO). Add the following callback URL and save:

    ```
    https://auth.airia.ai/OAuth/callback
    ```
  </Step>

  <Step title="Add API permissions">
    Select **Permissions** in the left sidebar, click **Add** next to the Jira API, and enable every scope listed under [Tools and Required Scopes](#tools-and-required-scopes) below. The [Granting All Scopes](#granting-all-scopes) section has both scope lists ready to paste in.
  </Step>

  <Step title="Copy your credentials">
    Select **Settings** and copy the **Client ID** and **Secret**.
  </Step>

  <Step title="Find your Cloud ID">
    Your Cloud ID is a UUID Airia uses to reach your specific Jira site. Visit the following URL, replacing `{your-site}` with your Atlassian domain, and copy the `cloudId` value from the response:

    ```
    https://{your-site}.atlassian.net/_edge/tenant_info
    ```
  </Step>

  <Step title="Add it to Airia">
    Add **Jira Cloud (OAuth)** as a server on a Gateway or Deployment, then enter your **Client ID**, **Client Secret**, and **Cloud ID**.
  </Step>
</Steps>

<Note>
  The **OAuth Scopes** field in Airia is optional. Leave it blank to request the standard scopes above, or fill it in to request a different set. If you customize it, make sure to include `offline_access` so your connection can refresh automatically.
</Note>

## Tools and Required Scopes

Every tool below needs a specific Jira scope before it will work. Tool names are what an agent actually calls, the same names you'd see in an agent's tool call log.

<Note>
  Atlassian scopes come in two flavors. **Classic** scopes are broad and recommended, granting one alone is enough for every tool that lists one. **Granular** scopes are narrower and only needed if you're building an OAuth app without classic scopes, in which case a tool needs every listed granular scope granted together. A few tools, mostly Jira Software board and sprint tools, have no classic equivalent at all and always need their granular scope(s) regardless of which approach you use.
</Note>

### Issues

| Tool                                            | What it does                                     | Scope(s) required                                                                                                                                                                                                                                                                            |
| ----------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_searchissuesjql`           | Search Jira issues using JQL query language.     | `read:jira-work` (Classic) or `read:issue-details:jira` and `read:field.default-value:jira` and `read:field.option:jira` and `read:field:jira` and `read:group:jira` (Granular)                                                                                                              |
| `jira_cloud_rest_api_getsearchapproximatecount` | Get approximate count of issues matching JQL.    | `read:jira-work` (Classic) or `read:issue-details:jira` and `read:field.default-value:jira` and `read:field.option:jira` and `read:field:jira` and `read:group:jira` (Granular)                                                                                                              |
| `jira_cloud_rest_api_bulkfetchissues`           | Fetch multiple issues by ID in bulk.             | `read:jira-work` (Classic) or `read:issue-meta:jira` and `read:issue-security-level:jira` and `read:issue.vote:jira` and `read:issue.changelog:jira` and `read:avatar:jira` and `read:issue:jira` and `read:status:jira` and `read:user:jira` and `read:field-configuration:jira` (Granular) |
| `jira_cloud_rest_api_getissue`                  | Get a single Jira issue by key or ID.            | `read:jira-work` (Classic) or `read:issue-meta:jira` and `read:issue-security-level:jira` and `read:issue.vote:jira` and `read:issue.changelog:jira` and `read:avatar:jira` and `read:issue:jira` and `read:status:jira` and `read:user:jira` and `read:field-configuration:jira` (Granular) |
| `jira_cloud_rest_api_updateissue`               | Update an existing Jira issue.                   | `write:jira-work` (Classic) or `write:issue:jira` (Granular)                                                                                                                                                                                                                                 |
| `jira_cloud_rest_api_deleteissue`               | Delete a Jira issue permanently.                 | `write:jira-work` (Classic) or `delete:issue:jira` (Granular)                                                                                                                                                                                                                                |
| `jira_cloud_rest_api_createissue`               | Create a new Jira issue.                         | `write:jira-work` (Classic) or `write:issue:jira` and `write:comment:jira` and `write:comment.property:jira` and `write:attachment:jira` and `read:issue:jira` (Granular)                                                                                                                    |
| `jira_cloud_rest_api_getissuetransitions`       | Get available workflow transitions for an issue. | `read:jira-work` (Classic) or `read:issue.transition:jira` and `read:status:jira` and `read:field-configuration:jira` (Granular)                                                                                                                                                             |
| `jira_cloud_rest_api_transitionissue`           | Transition an issue to a new status.             | `write:jira-work` (Classic) or `write:issue:jira` and `write:issue.property:jira` (Granular)                                                                                                                                                                                                 |
| `jira_cloud_rest_api_assignissue`               | Assign an issue to a user.                       | `write:jira-work` (Classic) or `write:issue:jira` (Granular)                                                                                                                                                                                                                                 |
| `jira_cloud_rest_api_getissuechangelog`         | Get issue change history.                        | `read:jira-work` (Classic) or `read:issue-meta:jira` and `read:avatar:jira` and `read:issue.changelog:jira` (Granular)                                                                                                                                                                       |
| `jira_cloud_rest_api_bulkcreateissues`          | Bulk create multiple issues.                     | `write:jira-work` (Classic) or `write:issue:jira` and `write:comment:jira` and `write:comment.property:jira` and `write:attachment:jira` and `read:issue:jira` (Granular)                                                                                                                    |
| `jira_cloud_rest_api_bulktransitionissues`      | Bulk transition multiple issues.                 | `write:jira-work` (Classic) or `write:issue:jira` and `read:issue:jira` (Granular)                                                                                                                                                                                                           |

### Comments

| Tool                                | What it does                    | Scope(s) required                                                                                                                                                                                                                              |
| ----------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getcomments`   | Get comments on an issue.       | `read:jira-work` (Classic) or `read:comment:jira` and `read:comment.property:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `read:avatar:jira` (Granular)                           |
| `jira_cloud_rest_api_addcomment`    | Add a comment to an issue.      | `write:jira-work` (Classic) or `read:comment:jira` and `read:comment.property:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `write:comment:jira` and `read:avatar:jira` (Granular) |
| `jira_cloud_rest_api_updatecomment` | Update an existing comment.     | `write:jira-work` (Classic) or `read:comment:jira` and `read:comment.property:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `write:comment:jira` and `read:avatar:jira` (Granular) |
| `jira_cloud_rest_api_deletecomment` | Delete a comment from an issue. | `write:jira-work` (Classic) or `delete:comment:jira` and `delete:comment.property:jira` (Granular)                                                                                                                                             |

### Attachments

| Tool                                   | What it does                   | Scope(s) required                                                                                                                                                                                                                                                                            |
| -------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getattachments`   | Get attachments on an issue.   | `read:jira-work` (Classic) or `read:issue-meta:jira` and `read:issue-security-level:jira` and `read:issue.vote:jira` and `read:issue.changelog:jira` and `read:avatar:jira` and `read:issue:jira` and `read:status:jira` and `read:user:jira` and `read:field-configuration:jira` (Granular) |
| `jira_cloud_rest_api_addattachment`    | Add an attachment to an issue. | `write:jira-work` (Classic) or `read:user:jira` and `write:attachment:jira` and `read:attachment:jira` and `read:avatar:jira` (Granular)                                                                                                                                                     |
| `jira_cloud_rest_api_deleteattachment` | Delete an attachment.          | `write:jira-work` (Classic) or `delete:attachment:jira` (Granular)                                                                                                                                                                                                                           |

### Issue Links

| Tool                                  | What it does                            | Scope(s) required                                                                                                                 |
| ------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_linkissues`      | Create a link between two issues.       | `write:jira-work` (Classic) or `write:comment:jira` and `write:issue:jira` and `write:issue-link:jira` (Granular)                 |
| `jira_cloud_rest_api_deleteissuelink` | Delete a link between issues.           | `write:jira-work` (Classic) or `delete:issue-link:jira` (Granular)                                                                |
| `jira_cloud_rest_api_getremotelinks`  | Get remote links on an issue.           | `read:jira-work` (Classic) or `read:issue.remote-link:jira` and `read:status:jira` (Granular)                                     |
| `jira_cloud_rest_api_addremotelink`   | Add a remote/external link to an issue. | `write:jira-work` (Classic) or `write:issue:jira` and `write:issue.remote-link:jira` and `read:issue.remote-link:jira` (Granular) |

### Worklogs

| Tool                                | What it does                              | Scope(s) required                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getworklogs`   | Get work logs (time entries) on an issue. | `read:jira-work` (Classic) or `read:group:jira` and `read:issue-worklog:jira` and `read:issue-worklog.property:jira` and `read:project-role:jira` and `read:user:jira` and `read:avatar:jira` (Granular)                                                                                                                          |
| `jira_cloud_rest_api_addworklog`    | Log time/work on an issue.                | `write:jira-work` (Classic) or `write:issue-worklog:jira` and `write:issue-worklog.property:jira` and `read:avatar:jira` and `read:group:jira` and `read:issue-worklog:jira` and `read:project-role:jira` and `read:user:jira` and `read:issue-worklog.property:jira` (Granular)                                                  |
| `jira_cloud_rest_api_updateworklog` | Update a work log entry.                  | `write:jira-work` (Classic) or `read:comment:jira` and `read:group:jira` and `read:issue-worklog:jira` and `read:issue-worklog.property:jira` and `read:project-role:jira` and `read:user:jira` and `write:comment:jira` and `write:issue-worklog:jira` and `write:issue-worklog.property:jira` and `read:avatar:jira` (Granular) |
| `jira_cloud_rest_api_deleteworklog` | Delete a work log entry.                  | `write:jira-work` (Classic) or `delete:issue-worklog:jira` and `delete:issue-worklog.property:jira` and `write:issue.time-tracking:jira` (Granular)                                                                                                                                                                               |

### Watchers

| Tool                                | What it does                    | Scope(s) required                                                                                              |
| ----------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getwatchers`   | Get users watching an issue.    | `read:jira-work` (Classic) or `read:issue.watcher:jira` and `read:user:jira` and `read:avatar:jira` (Granular) |
| `jira_cloud_rest_api_addwatcher`    | Add a watcher to an issue.      | `write:jira-work` (Classic) or `write:issue.watcher:jira` (Granular)                                           |
| `jira_cloud_rest_api_removewatcher` | Remove a watcher from an issue. | `write:jira-work` (Classic) or `write:issue.watcher:jira` (Granular)                                           |

### Votes

| Tool                             | What it does                    | Scope(s) required                                                                                                                                                  |
| -------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `jira_cloud_rest_api_getvotes`   | Get votes on an issue.          | `read:jira-work` (Classic) or `read:issue.vote:jira` and `read:user:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:group:jira` (Granular) |
| `jira_cloud_rest_api_addvote`    | Vote for an issue.              | `write:jira-work` (Classic) or `write:issue.vote:jira` (Granular)                                                                                                  |
| `jira_cloud_rest_api_removevote` | Remove your vote from an issue. | `write:jira-work` (Classic) or `write:issue.vote:jira` (Granular)                                                                                                  |

### Projects

| Tool                              | What it does                      | Scope(s) required                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getprojects` | Search and list Jira projects.    | `read:jira-work` (Classic) or `read:issue-type:jira` and `read:project:jira` and `read:project.property:jira` and `read:user:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:group:jira` and `read:issue-type-hierarchy:jira` and `read:project-category:jira` and `read:project-version:jira` and `read:project.component:jira` (Granular) |
| `jira_cloud_rest_api_getproject`  | Get a specific project's details. | `read:jira-work` (Classic) or `read:issue-type:jira` and `read:project:jira` and `read:project.property:jira` and `read:user:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:group:jira` and `read:issue-type-hierarchy:jira` and `read:project-category:jira` and `read:project-version:jira` and `read:project.component:jira` (Granular) |

### Components

| Tool                                       | What it does                         | Scope(s) required                                                                                                                                                                                                                         |
| ------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getprojectcomponents` | Get components in a project.         | `read:jira-work` (Classic) or `read:project:jira` and `read:project.component:jira` and `read:user:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:group:jira` (Granular)                                         |
| `jira_cloud_rest_api_createcomponent`      | Create a new component in a project. | `manage:jira-project` (Classic) or `read:project:jira` and `read:user:jira` and `write:project.component:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:group:jira` and `read:project.component:jira` (Granular) |

### Versions

| Tool                                     | What it does                        | Scope(s) required                                                                                          |
| ---------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getprojectversions` | Get versions/releases in a project. | `read:jira-work` (Classic) or `read:project-version:jira` (Granular)                                       |
| `jira_cloud_rest_api_createversion`      | Create a new version/release.       | `manage:jira-project` (Classic) or `write:project-version:jira` and `read:project-version:jira` (Granular) |
| `jira_cloud_rest_api_updateversion`      | Update or release a version.        | `manage:jira-project` (Classic) or `write:project-version:jira` and `read:project-version:jira` (Granular) |

### Boards

<Note>
  Jira Software's agile endpoints (Boards and Sprints) have no classic scope equivalent. Their granular scopes are always required, even if you otherwise use classic scopes for everything else.
</Note>

| Tool                                  | What it does                         | Scope(s) required                                              |
| ------------------------------------- | ------------------------------------ | -------------------------------------------------------------- |
| `jira_cloud_rest_api_getboards`       | Get all agile boards (Scrum/Kanban). | `read:board-scope:jira-software` and `read:project:jira`       |
| `jira_cloud_rest_api_getboardsprints` | Get sprints for a board.             | `read:sprint:jira-software`                                    |
| `jira_cloud_rest_api_getboardissues`  | Get issues on a board.               | `read:board-scope:jira-software` and `read:issue-details:jira` |

### Sprints

| Tool                                     | What it does             | Scope(s) required                                                             |
| ---------------------------------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getsprintissues`    | Get issues in a sprint.  | `read:sprint:jira-software` and `read:issue-details:jira` and `read:jql:jira` |
| `jira_cloud_rest_api_moveissuestosprint` | Move issues to a sprint. | `write:sprint:jira-software`                                                  |
| `jira_cloud_rest_api_createsprint`       | Create a new sprint.     | `write:sprint:jira-software`                                                  |
| `jira_cloud_rest_api_updatesprint`       | Update a sprint.         | `write:sprint:jira-software`                                                  |

### Users

| Tool                                        | What it does                                 | Scope(s) required                                                                                                                                                                     |
| ------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_searchusers`           | Search for Jira users.                       | `read:jira-user` (Classic) or `read:user:jira` and `read:user.property:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:group:jira` (Granular)                 |
| `jira_cloud_rest_api_getuser`               | Get a specific user's details.               | `read:jira-user` (Classic) or `read:application-role:jira` and `read:group:jira` and `read:user:jira` and `read:avatar:jira` (Granular)                                               |
| `jira_cloud_rest_api_getcurrentuser`        | Get current authenticated user.              | `read:jira-user` (Classic) or `read:application-role:jira` and `read:group:jira` and `read:user:jira` and `read:avatar:jira` (Granular)                                               |
| `jira_cloud_rest_api_searchassignableusers` | Get users assignable to an issue or project. | `read:jira-user` (Classic) or `read:issue:jira` and `read:project:jira` and `read:user:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:group:jira` (Granular) |

### Reference Data

| Tool                                  | What it does                             | Scope(s) required                                                                                                                                                              |
| ------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `jira_cloud_rest_api_getlabels`       | Get all labels used in Jira.             | `read:jira-work` (Classic) or `read:label:jira` (Granular)                                                                                                                     |
| `jira_cloud_rest_api_getpriorities`   | Get all priority levels.                 | `read:jira-work` (Classic) or `read:priority:jira` (Granular)                                                                                                                  |
| `jira_cloud_rest_api_getstatuses`     | Get all status values.                   | `read:jira-work` (Classic) or `read:status:jira` (Granular)                                                                                                                    |
| `jira_cloud_rest_api_getissuetypes`   | Get all issue types.                     | `read:jira-work` (Classic) or `read:issue-type:jira` and `read:avatar:jira` and `read:project-category:jira` and `read:project:jira` (Granular)                                |
| `jira_cloud_rest_api_getfields`       | Get all fields (standard and custom).    | `read:jira-work` (Classic) or `read:field:jira` and `read:avatar:jira` and `read:project-category:jira` and `read:project:jira` and `read:field-configuration:jira` (Granular) |
| `jira_cloud_rest_api_getfieldoptions` | Get options for a select/dropdown field. | `manage:jira-configuration` (Classic) or `read:field.option:jira` (Granular)                                                                                                   |

### Filters

| Tool                                     | What it does               | Scope(s) required                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getfilters`         | Search saved JQL filters.  | `read:jira-work` (Classic) or `read:filter:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `read:jql:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:issue-type-hierarchy:jira` (Granular)                                                                                                                                    |
| `jira_cloud_rest_api_getfavoritefilters` | Get your favorite filters. | `read:jira-work` (Classic) or `read:filter:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `read:jql:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:issue-type-hierarchy:jira` (Granular)                                                                                                                                    |
| `jira_cloud_rest_api_createfilter`       | Create a new saved filter. | `write:jira-work` (Classic) or `read:filter:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `write:filter:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:issue-type-hierarchy:jira` and `read:issue-type:jira` and `read:project-category:jira` and `read:project-version:jira` and `read:project.component:jira` (Granular) |
| `jira_cloud_rest_api_updatefilter`       | Update a saved filter.     | `write:jira-work` (Classic) or `write:filter:jira` and `read:filter:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `read:jql:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:issue-type-hierarchy:jira` (Granular)                                                                                                           |
| `jira_cloud_rest_api_deletefilter`       | Delete a saved filter.     | `write:jira-work` (Classic) or `delete:filter:jira` (Granular)                                                                                                                                                                                                                                                                                                                                                  |

### Dashboards

| Tool                                | What it does        | Scope(s) required                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_cloud_rest_api_getdashboards` | Get all dashboards. | `read:jira-work` (Classic) or `read:dashboard:jira` and `read:group:jira` and `read:project:jira` and `read:project-role:jira` and `read:user:jira` and `read:application-role:jira` and `read:avatar:jira` and `read:issue-type-hierarchy:jira` and `read:issue-type:jira` and `read:project-category:jira` and `read:project-version:jira` and `read:project.component:jira` (Granular) |

## Granting All Scopes

If you'd rather not cross-reference the table above tool by tool, enable every scope below in the Atlassian console and every tool becomes available at once.

**Classic scopes**

```
read:jira-user read:jira-work write:jira-work manage:jira-project manage:jira-configuration
```

**Granular scopes**

```
read:attachment:jira read:board-scope:jira-software write:board-scope:jira-software read:sprint:jira-software write:sprint:jira-software
```

<Note>
  Together, these two short lists cover every tool in the reference above. The five Classic scopes cover every tool that lists a Classic option, and the Granular list adds the handful of scopes Jira Software's Boards and Sprints tools need, since those have no Classic equivalent. You don't need to hunt down the long Granular lists shown per tool above unless you're deliberately building an OAuth app that avoids Classic scopes entirely.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sign-in fails or a consent screen shows an error" icon="user-lock">
    Double check the callback URL on your OAuth app is exactly `https://auth.airia.ai/OAuth/callback`, and that your Cloud ID is correct. A wrong Cloud ID connects successfully but every tool call fails, since Airia is pointed at a site that doesn't match the app's authorization.
  </Accordion>

  <Accordion title="A specific tool fails even though the connection works" icon="triangle-exclamation">
    Check the [Tools and Required Scopes](#tools-and-required-scopes) table above for the exact scope that tool needs, add it to your app registration, and reconnect.
  </Accordion>

  <Accordion title="The connection stops working after about an hour" icon="clock-rotate-left">
    This happens when `offline_access` wasn't included in the granted scopes, so Airia has no way to refresh the session. If you customized the **OAuth Scopes** field in Airia, add `offline_access` back in and reconnect.
  </Accordion>
</AccordionGroup>

## Learn More

* [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)
* [Jira Cloud scopes for OAuth 2.0](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/)
* [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
* [OAuth 2.0 for Atlassian apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)

## Jira Cloud (API Token)

<Tip>
  Airia also offers **Jira Cloud (API Token)**, a separate, Restricted server that most organizations will never see or need. It's not enabled by default. If you want to use it, talk to your Airia contact about adding it to your tenant, after which a Platform Admin, Admin, or Security Admin can turn it on from [Server Management](/mcps/admin-controls/server-management) using **Add Restricted Server**.
</Tip>

It exposes the exact same tools as Jira Cloud (OAuth) above, just with a different way of authenticating: every request runs as whichever Atlassian account owns the token, so there's no OAuth app, no Cloud ID, and no scopes to grant. The token has full access to whatever that account can already do in Jira.

<Steps>
  <Step title="Create an API token">
    Go to your Atlassian [API token settings](https://id.atlassian.com/manage-profile/security/api-tokens) and create a new token. Copy it, along with the email address of the Atlassian account it belongs to.
  </Step>

  <Step title="Base64 encode your credential">
    Combine your email and token as `{your email}:{your API token}`, then Base64 encode the whole string. On macOS or Linux, you can run:

    ```bash theme={null}
    echo -n "you@example.com:your-api-token" | base64
    ```
  </Step>

  <Step title="Add it to Airia">
    Add **Jira Cloud (API Token)** as a server on a Gateway or Deployment, then enter the encoded string as the credential, along with your Atlassian domain, the part before `.atlassian.net` in your site's URL.
  </Step>
</Steps>

<Note>
  The credential Airia needs is the Base64 encoding of `email:apitoken`, not the API token by itself. This method authenticates every request with a single token rather than individual user sign-in, so it's best suited to simpler or single-account setups.
</Note>