Skip to content

docs: Required scopes #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
edgarrmondragon merged 2 commits into from
Mar 25, 2026
Merged

docs: Required scopes #319

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1a0bb3
Fix API docs links in stream class docstrings
ReubenFrankel Mar 24, 2026
35c3a8e
Document required scopes per stream
ReubenFrankel Mar 25, 2026
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
39 changes: 39 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,45 @@ tap-jira uses **Basic Authentication** with Jira API tokens. All requests requir
}
```

#### Required Scopes

Stream | Classic scopes | Granular scopes
------ | -------------- | ---------------
`users` | `read:jira-user` | `read:application-role:jira`<br>`read:avatar:jira`<br>`read:group:jira`<br>`read:user:jira`
`fields` | `read:jira-work` | `read:avatar:jira`<br>`read:field-configuration:jira`<br>`read:field:jira`<br>`read:project-category:jira`<br>`read:project:jira`
`custom_field_contexts` | `manage:jira-configuration` | `read:custom-field-contextual-configuration:jira`<br>`read:field:jira`
`custom_field_options` | `manage:jira-configuration` | `read:field.option:jira`
`server_info` | Any | Any
`issue_types` | `read:jira-work` | `read:avatar:jira`<br>`read:issue-type:jira`<br>`read:project-category:jira`<br>`read:project:jira`
`workflow_statuses` | `read:jira-work` | `read:status:jira`
`projects` | `read:jira-work` | `read:application-role:jira`<br>`read:avatar:jira`<br>`read:group:jira`<br>`read:issue-type-hierarchy:jira`<br>`read:issue-type:jira`<br>`read:project-category:jira`<br>`read:project-version:jira`<br>`read:project.component:jira`<br>`read:project.property:jira`<br>`read:project:jira`<br>`read:user:jira`
`project_versions` | `read:jira-work` | `read:project-version:jira`
`issues` | `read:jira-work` | `read:audit-log:jira`<br>`read:avatar:jira`<br>`read:field-configuration:jira`<br>`read:issue-details:jira`<br>`read:issue-meta:jira`
`permissions` | `manage:jira-configuration` | `read:permission:jira`
`project_roles` | `manage:jira-configuration` | `read:avatar:jira`<br>`read:group:jira`<br>`read:project-category:jira`<br>`read:project-role:jira`<br>`read:project:jira`<br>`read:user:jira`
`priorities` | `read:jira-work` | `read:priority:jira`
`permission_holders` | `read:jira-work` | `read:application-role:jira`<br>`read:avatar:jira`<br>`read:field:jira`<br>`read:group:jira`<br>`read:permission-scheme:jira`<br>`read:permission:jira`<br>`read:project-category:jira`<br>`read:project-role:jira`<br>`read:project:jira`<br>`read:user:jira`
`boards` | N/A | `read:board-scope:jira-software`<br>`read:project:jira`
`sprints` | N/A | `read:sprint:jira-software`
`project_role_actors` | `read:jira-work`<br>`manage:jira-configuration` | `read:application-role:jira`<br>`read:avatar:jira`<br>`read:group:jira`<br>`read:issue-type-hierarchy:jira`<br>`read:issue-type:jira`<br>`read:project-category:jira`<br>`read:project-role:jira`<br>`read:project-version:jira`<br>`read:project.component:jira`<br>`read:project.property:jira`<br>`read:project:jira`<br>`read:user:jira`
`audit_records` | `manage:jira-configuration` | `read:audit-log:jira`<br>`read:user:jira`
`dashboards` | `read:jira-work` | `read:application-role:jira`<br>`read:avatar:jira`<br>`read:dashboard:jira`<br>`read:group:jira`<br>`read:issue-type-hierarchy:jira`<br>`read:issue-type:jira`<br>`read:project-category:jira`<br>`read:project-role:jira`<br>`read:project-version:jira`<br>`read:project.component:jira`<br>`read:project:jira`<br>`read:user:jira`
`filters` | `read:jira-work` | `read:application-role:jira`<br>`read:avatar:jira`<br>`read:filter:jira`<br>`read:group:jira`<br>`read:issue-type-hierarchy:jira`<br>`read:jql:jira`<br>`read:project-role:jira`<br>`read:project:jira`<br>`read:user:jira`
`filter_default_share_scopes` | `read:jira-work` | `read:filter.default-share-scope:jira`
`groups_pickers` | `read:jira-user` | `read:group:jira`
`licenses` | `manage:jira-configuration` | `read:license:jira`
`screens` | `manage:jira-project` | `read:avatar:jira`<br>`read:project-category:jira`<br>`read:project:jira`<br>`read:screen:jira`
`screen_schemes` | `manage:jira-project` | `read:issue-type-screen-scheme:jira`<br>`read:screen-scheme:jira`
`statuses` | `manage:jira-configuration` | `read:workflow:jira`
`resolutions` | `read:jira-work` | `read:resolution:jira`
`workflows` | `manage:jira-configuration` | `read:workflow:jira`
`issue_watchers` | `read:jira-work` | `read:avatar:jira`<br>`read:issue.watcher:jira`<br>`read:user:jira`
`issue_changelog` | `read:jira-work` | `read:avatar:jira`<br>`read:issue-meta:jira`<br>`read:issue.changelog:jira`
`issue_comments` | `read:jira-work` | `read:avatar:jira`<br>`read:comment.property:jira`<br>`read:comment:jira`<br>`read:group:jira`<br>`read:project-role:jira`<br>`read:project:jira`<br>`read:user:jira`
`issue_worklogs` | `read:jira-work` | `read:avatar:jira`<br>`read:group:jira`<br>`read:issue-worklog.property:jira`<br>`read:issue-worklog:jira`<br>`read:project-role:jira`<br>`read:user:jira`
`components` | `read:jira-work` | `read:application-role:jira`<br>`read:avatar:jira`<br>`read:group:jira`<br>`read:project.component:jira`<br>`read:project:jira`<br>`read:user:jira`


#### Cloud ID (Optional)

For OAuth2.0 or granular access tokens, you need to use Atlassian's cloud-based API URLs instead of your domain. When provided, `cloud_id` changes the API URL structure from `https://{domain}/rest/api/3` to `https://api.atlassian.com/ex/jira/{cloud_id}/rest/api/3`. Authentication still uses your Basic Auth credentials.
Expand Down
27 changes: 15 additions & 12 deletions tap_jira/streams.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@
class UsersStream(JiraStartAtPaginatedStream):
"""Users stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-users-search-get
"""

"""
Expand Down Expand Up @@ -428,7 +428,7 @@ class WorkflowStatusStream(JiraStartAtPaginatedStream):
class ProjectStream(JiraStartAtPaginatedStream):
"""Project stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get
"""

"""
Expand Down Expand Up @@ -505,7 +505,7 @@ def get_child_context(
class ProjectVersionStream(JiraStartAtPaginatedStream):
"""Project versions stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions/#api-rest-api-3-project-projectidorkey-version-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-versions/#api-rest-api-3-project-projectidorkey-versions-get
"""

parent_stream_type = ProjectStream
Expand Down Expand Up @@ -2483,7 +2483,8 @@ class PermissionHolderStream(JiraStartAtPaginatedStream):
class BoardStream(JiraStartAtPaginatedStream):
"""Board stream.

https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference/#sprint
* https://developer.atlassian.com/cloud/jira/software/rest/api-group-board/#api-rest-agile-1-0-board-get
* https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference/#board
"""

"""
Expand Down Expand Up @@ -2624,7 +2625,9 @@ def validate_response(self, response: requests.Response) -> None:
class ProjectRoleActorStream(JiraStartAtPaginatedStream):
"""Project role actor stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-role-actors/#api-rest-api-3-role-id-actors-get
* https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get
* https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles/#api-rest-api-3-role-get
* https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-project-roles/#api-rest-api-3-project-projectidorkey-role-id-get
"""

"""
Expand Down Expand Up @@ -3008,7 +3011,7 @@ class ScreensStream(JiraStartAtPaginatedStream):
class ScreenSchemesStream(JiraStartAtPaginatedStream):
"""Screen schemes stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-screen-tab-fields/#api-rest-api-3-screens-screenid-tabs-tabid-fields-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-screen-schemes/#api-rest-api-3-screenscheme-get
"""

"""
Expand Down Expand Up @@ -3045,7 +3048,7 @@ class ScreenSchemesStream(JiraStartAtPaginatedStream):
class StatusStream(JiraStartAtPaginatedStream):
"""Statuses stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-screen-tab-fields/#api-rest-api-3-screens-screenid-tabs-tabid-fields-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-status/#api-rest-api-3-statuses-search-get
"""

"""
Expand Down Expand Up @@ -3082,7 +3085,7 @@ class StatusStream(JiraStartAtPaginatedStream):
class Resolutions(JiraStartAtPaginatedStream):
"""Resolution stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-resolutions/#api-rest-api-3-resolution-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-resolutions/#api-rest-api-3-resolution-search-get
"""

"""
Expand Down Expand Up @@ -3115,7 +3118,7 @@ class Resolutions(JiraStartAtPaginatedStream):
class WorkflowStream(JiraStartAtPaginatedStream):
"""Workflows stream.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflows/#api-rest-api-3-workflow-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflows/#api-rest-api-3-workflows-search-get
"""

"""
Expand Down Expand Up @@ -3270,7 +3273,7 @@ class WorkflowStream(JiraStartAtPaginatedStream):
class IssueWatchersStream(JiraStartAtPaginatedStream):
"""Issue Watchers.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflows/#api-rest-api-3-workflow-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-watchers/#api-rest-api-3-issue-issueidorkey-watchers-get
"""

"""
Expand Down Expand Up @@ -3309,7 +3312,7 @@ def post_process(self, row: Record, context: Context | None = None) -> Record:
class IssueChangeLogStream(JiraStartAtPaginatedStream):
"""Issue Change Log.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-workflows/#api-rest-api-3-workflow-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-changelog-get
"""

"""
Expand Down Expand Up @@ -3435,7 +3438,7 @@ def post_process(self, row: Record, context: Context | None = None) -> Record:
class IssueWorklogs(JiraStartAtPaginatedStream):
"""Issue Worklogs.

https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-comments/#api-rest-api-3-issue-issueidorkey-comment-get
https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-worklogs/#api-rest-api-3-issue-issueidorkey-worklog-get
"""

"""
Expand Down
Loading