setup

Jira

Purpose

Collects one Jira Cloud site's users, groups and group membership, admin groups, projects, project roles and their actors, and permission schemes. Use it to see who can administer or browse each project.

This sync module is separate from the Jira ticketing integration under Settings > Integrations. That integration uses OAuth to create issues; this module reads access data with an API token. Configure each independently.

tip

Secret fields below accept either an AWS Secrets Manager ARN or a value pasted directly into SubImage's managed vault. See Secrets for details.

Required Fields

Field Secret? Description
jira_cloud_id No Jira Cloud site ID (UUID). Scopes every synced ID to this site.
jira_email No Email address of the Atlassian account that owns the API token
jira_api_token Yes Atlassian API token: its AWS Secrets Manager ARN, or the vault value

Optional Fields

Field Description
jira_site_url Site origin, e.g. https://acme.atlassian.net. Only needed for an unscoped API token; leave empty for a scoped one.

Required Permissions

The token's account needs both Jira global permissions below. The sync checks them before reading anything, because a less privileged account gets a silently filtered project list.

Permission Purpose
Browse users and groups List every user and group, including membership
Administer Jira List every project and read its roles and permission scheme

A scoped token also needs these granular read scopes:

read:application-role:jira
read:avatar:jira
read:field:jira
read:group:jira
read:issue-type-hierarchy:jira
read:issue-type:jira
read:permission-scheme:jira
read:permission:jira
read:project-category:jira
read:project-role:jira
read:project-version:jira
read:project.component:jira
read:project.property:jira
read:project:jira
read:user:jira

Setup Steps

  1. Find your site's Cloud ID by opening https://<your-site>.atlassian.net/_edge/tenant_info and copying the cloudId value.
  2. Sign in as an account with the two global permissions above and open API token settings.
  3. Select Create API token with scopes, name it SubImage, choose an expiry date, and pick Jira as the app.
  4. Add all 15 read scopes listed above and create the token. Copy it now; Atlassian only shows it once.
  5. In SubImage, enter jira_cloud_id, the account's jira_email, and the token in jira_api_token.
  6. Save the module and run a sync.

Notes

  • Only Jira Cloud is supported. Jira Data Center and Server are not.
  • The sync is read-only; it only issues GET requests and changes no Jira configuration.
  • An existing unscoped API token also works. Set jira_site_url to your site's https://<site>.atlassian.net origin; the sync verifies it matches the Cloud ID.
  • Atlassian profile visibility can hide some users' email addresses, even from administrators. Those users are still synced by account ID.
  • Atlassian API tokens expire. Rotate the token before its expiry date and update the module configuration.

Troubleshooting

  • Jira permissions missing: the token's account lacks Administer Jira or Browse users and groups. Grant both, or use a token owned by a Jira administrator.
  • Jira site misconfigured: the site is not Jira Cloud, or jira_site_url points at a different site than jira_cloud_id.
  • 401 Unauthorized: the token expired or was revoked, jira_email is not the token owner, or an unscoped token is missing jira_site_url.
  • 403 Forbidden: a scoped token is missing one of the read scopes above. Create a new token with all 15.
On this page
PurposeRequired FieldsOptional FieldsRequired PermissionsSetup StepsNotesTroubleshooting