Jira
Create and sync Jira issues from Safeguard. The Jira permissions and API token scopes Safeguard needs, which tokens work, and step-by-step setup.
What it does
The Jira card connects Safeguard to one Jira Cloud project. Safeguard creates Jira issues for the findings and work you send to Jira, updates them, and moves them through your workflow using the status mapping you set (new, in progress, under review, completed). It checks the issues it created every few minutes to pick up changes made in Jira. Find the card under Integrations on the Notification tab.
Public vs private
This does not apply to Jira: you always connect your own Jira Cloud site with an account's API token. Jira Data Center is not supported yet.
Supported auth methods
| Method | Use it when | Notes |
|---|---|---|
| Atlassian API token (classic, unscoped) with the account email | Recommended default | Enter your Jira site address, such as https://your-site.atlassian.net |
| Atlassian API token with scopes | You want the token limited to the Jira scopes below | Atlassian requires scoped tokens to be used through https://api.atlassian.com/ex/jira/<cloudId>, so enter that address as the site |
| OAuth (sign in with Atlassian) | Not available yet |
Permissions required
Safeguard reads projects and statuses, and creates and updates issues in the project you choose. It never deletes issues, projects or users. The token acts as its account, so the account's Jira permissions decide what works.
Jira permissions of the account
| Jira permission | Required? | What Safeguard uses it for |
|---|---|---|
| Browse projects | Required | Listing projects, reading the project's statuses, and reading the issues it created |
| Create issues | Required | Creating issues |
| Edit issues | Required | Updating the issues it created |
| Transition issues | Required | Moving issues to the mapped status |
| Browse users and groups (global permission) | Optional | Finding the Default Assignee by email. Without it, the search returns no one |
| Assign issues | Optional | Setting the Default Assignee on new issues |
API token with scopes
| Scope | Required? | What Safeguard uses it for |
|---|---|---|
read:jira-user | Required | Checking the token (/rest/api/3/myself) and finding the default assignee |
read:jira-work | Required | Listing projects and statuses, and reading issues |
write:jira-work | Required | Creating, updating and transitioning issues |
Least privilege: a dedicated Jira account with the project permissions above on the one project, and a token with those three scopes.
Token types
| Token type | Works? | Notes |
|---|---|---|
| API token without scopes | Yes | Acts with the full Jira permissions of its account, limited by the project's permission scheme |
| API token with scopes (Jira app) | Yes | Use the api.atlassian.com/ex/jira/<cloudId> address as the site |
| Your Atlassian password | No | Jira Cloud's REST API takes an API token |
| Jira Data Center personal access token | No | Data Center is not supported yet |
| Service account | Yes | A token of a dedicated Atlassian account works the same way |
Expiry: Atlassian API tokens expire after 1 to 365 days (one year by default). When the token expires, issue creation and sync stop until you paste a new one.
What we never need: Jira administrator permissions, delete permissions, manage:jira-configuration or any admin scope.
Step-by-step setup
Create the credential in Atlassian
- Open the API tokens page of your Atlassian account (
https://id.atlassian.com/manage-profile/security/api-tokens). - Select Create API token (or Create API token with scopes, choose Jira, and select the three scopes above).
- Enter a name and an expiration date, select Create, and copy the token. Atlassian shows it only once.
Or check it with curl
Atlassian has no CLI for creating API tokens. To check a token the way Safeguard does:
curl -s -u 'you@example.com:<api-token>' https://your-site.atlassian.net/rest/api/3/myself
curl -s -u 'you@example.com:<api-token>' "https://your-site.atlassian.net/rest/api/3/project/search"Connect it in Safeguard
- Open Integrations and choose the Notification tab.
- Click Connect on the Jira card.
- Enter a Name. Under Where does Jira run?, keep Cloud and enter your Site URL.
- Paste the token into Jira Token and enter the account email under Username. Optionally enter a Default Assignee email and a Description.
- Click Next. "Jira connection validated successfully" means Jira accepted the token. Choose the project under Select Project.
- Under Status Mapping, map Safeguard's states to your Jira statuses, then click Connect.
Webhooks and triggers
This card has no webhooks to set up. Safeguard pushes changes to the issues it created and checks those issues in Jira every few minutes to pick up status and field changes.
What we read and store
- Read: the token's account, your projects, the chosen project's statuses, user search results for the default assignee, and the issues Safeguard created.
- Stored: the connection's settings, project and status mapping, links between Safeguard items and Jira issues, and the API token, which is encrypted at rest.
- Sent to Jira: issue titles, descriptions and status changes about your Safeguard findings.
- No customer data from this integration is sent to third-party LLMs.
Troubleshooting
| Message you see | Cause | Fix |
|---|---|---|
Failed to validate Jira connection | Safeguard could not reach the site | Check the Site URL |
| Jira's own error text, shown as is (for example an authentication error) | Jira refused the email and token | Use the account email as Username and a current API token |
Jira answered with a redirect, which Safeguard does not follow. Enter the site's current address. | The site moved or was renamed | Enter the current https://<site>.atlassian.net address |
This server address isn't allowed: ... | The address is not an Atlassian Cloud site | Enter your atlassian.net site, or the api.atlassian.com/ex/jira/<cloudId> address for a scoped token |
No projects found | The account cannot browse any project, or a scoped token lacks read:jira-work | Grant Browse projects, or add the scope |
| Issues are not created or do not move | The account lacks Create issues, Edit issues or Transition issues on the project | Add the permissions in the project's permission scheme |
Rotation and disconnect
- Rotate: create a new API token, open the Jira connection on the Notification tab, choose Update, paste the new token and save. Then revoke the old token on the Atlassian API tokens page.
- Disconnect: choose Delete on the connection, then revoke the token in your Atlassian account. Issues already created stay in Jira.
Vendor references
- Manage API tokens for your Atlassian account, checked 2026-10-16.
- Jira Cloud platform REST API v3 specification, checked 2026-10-16.