Skip to content

docs: Document Atlassian OAuth permissions and service account requirements #319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
prithvi2206 merged 1 commit into from
Mar 24, 2026
Merged

docs: Document Atlassian OAuth permissions and service account requirements #319

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions src/content/docs/docs/integrations/atlassian-integration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,47 @@ Promptless supports two types of Jira integrations depending on your Jira deploy
Jira Data Center is in Beta. Please contact the Promptless team at [help@gopromptless.ai](mailto:help@gopromptless.ai) to connect your Jira Data Center instance to Promptless.
</Info>

## Permissions Required

The OAuth consent screen displays the permissions Promptless requests when you connect Atlassian. Promptless requests only the scopes needed to read Jira issues and Confluence pages for documentation context.
Copy link
Copy Markdown
Contributor Author

@promptless promptless bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OAuth scopes defined in IntegrationsList.tsx - includes classic scopes (read:jira-work, write:jira-work, read:jira-user) and Confluence scopes (read:confluence-space.summary, read:confluence-content.all, plus granular scopes for API v2 compatibility)

Source: https://github.com/Promptless/promptless/blob/main/promptless-dashboard/src/components/IntegrationsList.tsx


### Jira Scopes

| Scope | Purpose |
|-------|---------|
| `read:jira-work` | Read Jira issues, projects, and work data |
| `write:jira-work` | Required by Atlassian for API access; Promptless uses read-only operations |
| `read:jira-user` | Read user information for issue context |

### Confluence Scopes

| Scope | Purpose |
|-------|---------|
| `read:confluence-space.summary` | Read space names and metadata |
| `read:confluence-content.all` | Read page content for documentation context |
| `read:space:confluence` | Read space information (granular scope) |
| `read:page:confluence` | Read individual pages (granular scope) |
| `read:content:confluence` | Read content body (granular scope) |

### Additional Scopes

| Scope | Purpose |
|-------|---------|
| `offline_access` | Allow Promptless to refresh tokens without re-authentication |

<Info>
Confluence scopes include both classic and granular variants for compatibility with Atlassian's API v2. Promptless only reads issue and page data—it does not write to Jira or Confluence. The `write:jira-work` scope is required by Atlassian's OAuth system for certain read operations.
</Info>

### Service Account Permissions

When creating a dedicated Atlassian account for Promptless, the account needs:

1. **Jira access**: The "User" role (not "User access admin") on projects you want Promptless to reference
2. **Confluence access**: "Can view" permission on spaces you want Promptless to search

The account does not need administrative permissions. See [Provisioning an Atlassian Account for Promptless](#provisioning-an-atlassian-account-for-promptless) for step-by-step instructions.

## Jira Cloud Installation

For Atlassian Cloud-hosted Jira instances:
Expand Down
Loading