Jira Cloud

Add Jira Cloud to vScope

vScope connects to Jira Cloud using Basic Auth (username + API token). The username is the account email.

Create a service account and API token

Note

You must be a Jira organization admin to create service accounts, create groups, and grant global permissions.

1. Go to admin.atlassian.com.
2. Select Directory -> Service Accounts -> Create a Service Account.
3. Enter a name like vScope.
4. Under App roles, select role User for Jira, Projects, and Goals.
5. Select Create credentials, choose API token, enter a name, and set an expiry as far ahead as possible.
6. Select the required API scopes (see Required API token scopes) and create the token.
7. Copy the token now, because it will not be shown after this step.
8. In vScope, enter the service account username and its API token when creating the Jira Cloud credential.

Inventory visibility is limited by the permissions of the service account.

Create a group for the service account

Create a group so you can assign the required global permission later:

1. Go to admin.atlassian.com.
2. Select Directory -> Groups -> Create group.
3. Enter a name like vScope Service Accounts and create the group.
4. To add the service account to the group, go to Directory -> Service Accounts, open the service account, then use the … menu to select Add to group and choose the group you created.

Required Jira permissions

Listing users and groups requires the global permission Browse users and groups. In Jira admin settings, go to Security -> Global permissions, then grant Browse users and groups to the service account group that the service account is part of.

Required API token scopes

For a complete inventory, the API token must include these scopes.

• read:account
• read:jira-user
• read:jira-work
• read:avatar:jira
• read:group:jira
• read:user:jira

For partial inventory, see the permission requirements listed in the Jira Cloud credential in vScope.

Find the API base URL

1. Open your Jira site in a browser. The URL looks like https://<your-site>.atlassian.net.
2. Open https://<your-site>.atlassian.net/_edge/tenant_info to find your cloud ID.
3. Copy the value of cloudId from the response, for example:

{"cloudId":"c1bfd74b-1234-4f5a-96b1-abcdef123456"}

4. Build the API base URL using the gateway format https://api.atlassian.com/ex/jira/<cloudId>. For example: https://api.atlassian.com/ex/jira/c1bfd74b-1234-4f5a-96b1-abcdef123456

Add the Jira Cloud credential in vScope

1. Navigate to Discovery > Credentials.
2. Click Create credential and choose Jira Cloud.
3. Enter the API base URL in Base URL.
4. Enter the service account email in Username.
5. Enter the API token in Password.

Inventory settings

Configure inventory in Discovery > Inventory settings:

• Accounts: enable or disable user inventory.
• Groups: enable or disable group inventory.
• Work Items: enable or disable work item (issue) inventory.
• Project keys to include: limit work item inventory to specific project keys.
• Statuses to include: limit work item inventory to specific statuses.
• Statuses to exclude: exclude work items with specific statuses.

Troubleshooting

Authentication errors

If you see 401 Unauthorized, confirm the API token is valid and matches the service account in Username. If you see 403 Forbidden when listing users or groups, confirm the service account group has Browse users and groups and the API token includes the required scopes.

Email visibility

If user emails are missing, Jira profile visibility settings are hiding them. For Jira, hidden fields are omitted from the user response. For Confluence, hidden fields are returned as empty strings.

To include emails in inventory, ask users to set Email address visibility to Public in their Atlassian profile.