Skip to content

PORT-14744 Update Jira Integration Docs to Reflect Scoped API Token Requirements #2330

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
merged 5 commits into from
May 22, 2025
Merged

PORT-14744 Update Jira Integration Docs to Reflect Scoped API Token Requirements #2330

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a428210
Add required OAuth scopes for Jira integration and note API token dep…
kodjomiles May 21, 2025
93d4b1d
Update Jira documentation to reflect API token scope requirements and…
kodjomiles May 22, 2025
2ca1af9
Merge branch 'main' into PORT-14744-update-jira-integration-docs-to-r…
kodjomiles May 22, 2025
9aaf80d
Update Jira documentation to include required API token scopes config…
kodjomiles May 22, 2025
0d9ac52
Merge branch 'PORT-14744-update-jira-integration-docs-to-reflect-scop…
kodjomiles May 22, 2025
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
25 changes: 22 additions & 3 deletions ...uild-your-software-catalog/sync-data-to-catalog/project-management/jira/jira.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,24 @@ It is possible to reference any field that appears in the API responses linked b

## Setup

### Required API Token Scopes

:::warning Jira API token deprecation
Jira is deprecating API tokens without scopes. When creating Jira API tokens, you must configure the following required scopes for the integration to function properly.
:::

The Port Jira integration requires the following API token scopes:

| Scope | What it lets the app do | Why the integration needs it |
|-------|-------------------------|------------------------------|
| **read:account** | Read the basic Atlassian ID profile (account ID, display name, avatar). | Map actions and audit trails to the correct end-user and comply with GDPR "right to access/erase". |
| **read:jira-user** | View Jira user profiles (names, emails, avatars). | Display assignees/reporters and resolve user IDs when creating or updating issues. |
| **read:jira-work** | View Jira projects, issues, attachments, comments, worklogs, etc. | Sync Jira data into Port dashboards and run read-only analytics. |
| **write:jira-work** | Create or update issues, comments, worklogs; transition issues. | Push findings or automated actions back into Jira (e.g., open a ticket, add a comment, close an issue). |
| **manage:jira-project** | Create/edit project-level configuration (components, versions, custom fields). | Automatically provision required project settings or keep custom fields in sync. |
| **manage:jira-webhook** | Register, update, or delete dynamic webhooks. | Receive real-time callbacks when issues change instead of polling. |


Choose one of the following installation methods:


Expand Down Expand Up @@ -176,7 +194,7 @@ This table summarizes the available parameters for the installation.
| `port.clientSecret` | Your port [client secret](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ |
| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ |
| `integration.secrets.atlassianUserEmail` | The email of the user used to query Jira | [email protected] | ✅ |
| `integration.secrets.atlassianUserToken` | [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) generated by the user | | ✅ |
| `integration.secrets.atlassianUserToken` | [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) generated by the user. Make sure to configure the [required scopes](#required-api-token-scopes). | | ✅ |
| `integration.config.atlassianOrganizationId` | Your Atlassian Organization ID is required to sync teams and team members. [Follow the Atlassian documentation](https://confluence.atlassian.com/jirakb/what-it-is-the-organization-id-and-where-to-find-it-1207189876.html) on how to find your Organization ID | | ❌ |
| `integration.config.jiraHost` | The URL of your Jira | https://example.atlassian.net | ✅ |
| `integration.config.appHost` | The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Jira | https://my-ocean-integration.com | ✅ |
Expand Down Expand Up @@ -211,7 +229,7 @@ Make sure to configure the following [Github Secrets](https://docs.github.com/en
| `port_base_url` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ |
| `config -> jira_host` | The URL of your Jira | https://example.atlassian.net | ✅ |
| `config -> atlassian_user_email` | The email of the user used to query Jira | [email protected] | ✅ |
| `config -> atlassian_user_token` | [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) generated by the user | | ✅ |
| `config -> atlassian_user_token` | [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) generated by the user. Make sure to configure the [required scopes](#required-api-token-scopes). | | ✅ |
| `config -> atlassian_organization_id` |Your Atlassian Organization ID is required to sync teams and team members. [Follow the Atlassian documentation](https://confluence.atlassian.com/jirakb/what-it-is-the-organization-id-and-where-to-find-it-1207189876.html) on how to find your Organization ID | | ❌ |
| `initialize_port_resources` | Default true, When set to true the integration will create default blueprints and the port App config Mapping. Read more about [initializePortResources](https://ocean.getport.io/develop-an-integration/integration-configuration/#initializeportresources---initialize-port-resources) | | ❌ |
| `send_raw_data_examples` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true | | ❌ |
Expand Down Expand Up @@ -1418,7 +1436,8 @@ In addition, it requires a Jira API token that is provided as a parameter to the
1. Log in to your [Jira account](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Click Create API token.
3. From the dialog that appears, enter a memorable and concise Label for your token and click **Create**.
4. Click **Copy** to copy the token to your clipboard, you will not have another opportunity to view the token value after you leave this page.
4. Make sure to configure the [required scopes](#required-api-token-scopes) for the token.
5. Click **Copy** to copy the token to your clipboard, you will not have another opportunity to view the token value after you leave this page.

Use the following Python script to ingest historical Jira issues into port:

Expand Down