Generate API tokens for Splunk Add-on for Jira Cloud¶
Jira Cloud uses an API token to authenticate API calls. The add-on supports both classic API tokens for Atlassian user accounts and scoped API tokens for Atlassian service accounts.
Generate a classic API token¶
You must have the proper permissions to generate API tokens. Follow the instructions in Manage API tokens for your Atlassian account to create a classic API token, then make a copy of it to use later.
Generate a scoped service account API token¶
Follow the instructions in Manage API tokens for service accounts to create a scoped API token. Grant the service account product access and Jira permissions for every add-on feature that will use the token.
Every scoped token must include these scopes because account validation calls GET /rest/api/3/myself:
read:application-role:jiraread:group:jiraread:user:jiraread:avatar:jira
Add the scopes and Jira permissions for every feature that will use the token. The lists below reflect the Atlassian REST API requirements for the endpoints used by the add-on.
| Add-on feature | Additional scopes | Jira permissions |
|---|---|---|
| Jira Issues input | read:issue-details:jira, read:audit-log:jira, read:avatar:jira, read:field-configuration:jira, read:issue-meta:jira |
Browse Projects for every collected project and issue-level security permission when configured. See Search for issues using JQL enhanced search. |
| Jira Users input | The validation scopes already include all required scopes. | Browse users and groups global permission. See Get all users. |
| Project selection | read:issue-type:jira, read:project:jira, read:project.property:jira, read:user:jira, read:application-role:jira, read:avatar:jira, read:group:jira, read:issue-type-hierarchy:jira, read:project-category:jira, read:project-version:jira, read:project.component:jira |
Browse Projects or Administer Projects for each project, or Administer Jira globally. See Get projects paginated. |
| Jira Audit input | read:audit-log:jira, read:user:jira |
Administer Jira global permission. See Get audit records. |
Atlassian lists read:audit-log:jira as a required granular scope for the enhanced JQL search endpoint used by the Issues input. This scope requirement does not mean that the Issues input collects audit records or requires the Administer Jira global permission.
The Jira issue alert action uses different endpoints depending on its configuration. Grant the union of scopes for the operations you enable:
| Alert action operation | Additional scopes | Jira permissions |
|---|---|---|
| Validate the project | The Project selection scopes above. | Browse Projects for the selected project. See Get project. |
| Read custom-field metadata | read:field:jira, read:avatar:jira, read:project-category:jira, read:project:jira, read:field-configuration:jira |
No additional Jira permission; returned fields are limited to visible projects. See Get fields. |
| Validate priority | manage:jira-configuration |
Permission to access Jira. See Search priorities. |
| Create issue | write:issue:jira, write:comment:jira, write:comment.property:jira, write:attachment:jira, read:issue:jira |
Browse Projects and Create Issues for the project. See Create issue. |
| Update issue | write:issue:jira |
Browse Projects and Edit Issues; issue-level security permission when configured. See Edit issue. |
| Read available transitions | read:issue.transition:jira, read:status:jira, read:field-configuration:jira |
Browse Projects and Transition Issues; issue-level security permission when configured. See Get transitions. |
| Transition issue | write:issue:jira, write:issue.property:jira |
Browse Projects and Transition Issues; issue-level security permission when configured. See Transition issue. |
Atlassian can change endpoint requirements. Before creating a token, verify the scope list on each linked endpoint page. Scopes cannot be changed after a service account token is created.
The add-on discovers the site’s Cloud ID from the configured Jira domain. Do not enter an organization ID in place of the Jira domain.
Troubleshoot service account authentication¶
If Jira returns 401 Unauthorized, verify all of the following:
- The configured user name is the email address of the service account that owns the token.
- The token is active and has not expired or been revoked.
- The service account has Jira product access.
- The token contains the scopes required for every enabled add-on feature.
- The service account has the Jira permissions required for the projects and operations it uses.
- Atlassian IP allowlists and data security policies allow requests from the Splunk instance.
Service account tokens are scoped and the add-on sends their Jira REST requests through https://api.atlassian.com/ex/jira/<cloudId>/. Do not test a service account token by sending it directly to https://<domain>.atlassian.net/rest/api/....