Jira Configuration#

Configure a Jira Cloud site and an API token owned by an account with permission to read its users, groups, projects, and permission configuration.

Prerequisites#

Find the site’s stable Cloud ID in the Atlassian administration URL, or use the documented Cloud ID lookup. Use this UUID for --jira-cloud-id; it scopes graph identifiers even after a site rename. Jira Data Center and Server are not supported.

Authentication#

Scoped API token#

  1. Open the importing account’s API token settings and select Create API token with scopes. Complete identity verification if prompted.

  2. Name it Cartography, choose an expiry date, and select Jira as the app.

  3. Add all 15 granular read scopes listed under Required Permissions below, review the selection, and create the token.

  4. Copy the token before closing the dialog; Atlassian only displays it once.

See Atlassian’s API token instructions for details. Cartography sends Basic authentication using the account’s email and token to https://api.atlassian.com/ex/jira/<cloud-id>/rest/api/3. Store the token in JIRA_API_TOKEN or another environment variable selected with --jira-api-token-env-var.

Unscoped API token#

For an existing unscoped token, also provide --jira-site-url https://example.atlassian.net. This uses the site’s REST API origin with the same email/token credentials. The site URL must correspond to the configured Cloud ID; Cartography verifies this before inventory begins. HTTPS Atlassian Cloud site origins are the only accepted override destinations; redirects are rejected.

Required Permissions#

Permission

Purpose

Browse users and groups

List all users and groups, including group membership.

Administer Jira

Enumerate all live projects and read every project’s roles and scheme assignment.

Both global permissions are checked before inventory begins. A less privileged account could receive a successful but filtered project listing, so this module requires these permissions instead of accepting that incomplete inventory. The API token is only used for GET requests; no Jira configuration is changed.

For scoped tokens, enable the following union of granular read scopes documented for the GET endpoints used by this module:

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

The project listing endpoint requires its documented project and issue-type read scopes even though the module does not ingest issues. Token scopes do not substitute for the account’s Jira permissions. The endpoint references also list the classic OAuth scopes read:jira-user, read:jira-work, and manage:jira-configuration (group membership); OAuth authorization flows are not implemented by this module.

Configure Cartography#

Option

Required

Meaning

--jira-cloud-id

Yes

Stable Jira Cloud site UUID.

--jira-email

Yes

API-token owner’s email address.

--jira-api-token-env-var

No

Token environment variable, default JIRA_API_TOKEN.

--jira-site-url

For unscoped tokens

HTTPS Atlassian site origin; otherwise the scoped-token gateway is used.

Run Cartography#

export JIRA_API_TOKEN='your-api-token'
cartography --neo4j-uri bolt://localhost:7687 \
  --selected-modules jira \
  --jira-cloud-id 11111111-1111-4111-8111-111111111111 \
  --jira-email reader@example.com

To link accounts to canonical users, select jira,ontology and add --ontology-users-source jira.

Troubleshooting#

  • 401/403: Check token expiry, token scopes, email address, and the two required Jira global permissions. Scoped tokens use the gateway; unscoped tokens use the site URL override.

  • 429 or transient failures: The client retries GET requests up to three times on 429, 502, 503, and 504. Each Retry-After delay is capped at eight seconds; without that header, retries use exponential backoff. Exhausted retries abort the snapshot and preserve the previous graph. The connect timeout is 10 seconds and the socket read timeout is 60 seconds; these are not an overall request deadline.

  • Missing emails: Atlassian profile visibility may hide an email even from administrators. The account is still inventoried by account ID.

  • Incomplete reads: A failed or malformed required response aborts before graph writes and cleanup. Successful syncs remove stale records only within the configured Cloud ID.

  • Admin or team-managed coverage: See the group and project schema descriptions. Bulk get groups, including its admin access filters, is experimental and may change; unsupported responses abort the sync rather than guessing access.

References#