API Key Permissions for setting up the Jira Integration

Jira Server Options

The TerraTrue Jira integration supports both Jira Cloud and Jira Server (on-premise) and utilizes the REST APIs available with either option.

We support the latest version of the Jira Cloud REST API
- Documentation link - The Jira Cloud platform REST API
We support version 9.* of the Jira Server REST API.
- Documentation link - REST API Reference 9.1.0

Permissions Required

For our integration to operate as designed, the API key configured in TerraTrue needs to be permitted to make the set of REST calls outlined below.

Jira Permission Schemes

Jira Cloud permissions details are enumerated inline in the table below. In contrast, Jira Server does not supply this level of documentation per endpoint, but does provide a Permissions Overview.

The Jira Cloud API supports a “Get My Permissions” endpoint, Jira Server supports a similar GET /rest/api/2/mypermissions endpoint.

Jira Cloud also supports “Get Permitted Projects” can be useful to ensure the correct project are visible to TerrarTrue

Jira Endpoints

The table lists all the REST API endpoints the Terratrue integration uses. We leverage a shared path /rest/api/latest that is exposed on both Jira Cloud and Jira Server. We specifically call out any differences between the server options.

Endpoint	Path	Cloud/ Server/ Both	Jira Cloud docs	Jira Cloud Permissions	Notes
Create issue	POST /rest/api/latest/ issue	Both	link	Browse projects and Create issues project permissions for the project in which the issue or subtask is created.
Add comment to issue	POST /rest/api/latest/ issue/{issueNumber}/ comment	Both	link	Browse projects and Add comments project permission for the project that the issue containing the comment is in. If issue-level security is configured, issue-level security permission to view the issue.
Update issue priority, label	PUT /rest/api/latest/ issue/{issueNumber}	Both	link	Browse projects and Edit issues project permission for the project that the issue is in. If issue-level security is configured, issue-level security permission to view the issue.
Get all projects	GET /rest/api/latest/ project	Both	link	Projects are returned only where the user has Browse Projects or Administer projects permission for the project.	TerraTrue uses the paginated endpoint too where possible but it is not available in the Jira Server REST API.
Get Create Issue Metadata	GET /rest/api/latest/ issue/createmeta? projectKeys={projectKey}& expand= projects.issuetypes. fields	Cloud	link	Create issues project permission in the requested projects.	This endpoint was removed from the Jira Server REST API as of version 8.4.0
Get issue types for project	GET /rest/api/latest/ createmeta/ {projectKey}/ issuetypes	Server	-	-	One of the endpoints added to replace “Get Create Issue Metadata”
Get fields for issue type	GET /rest/api/latest/ createmeta/ {projectKey}/ issuetypes/ {issueNumber}	Server	-	-	One of the endpoints added to replace “Get Create Issue Metadata”
Search for issues using JQL	GET /rest/api/latest/ search?jql= project= '{projectKey} ORDER BY key DESC& validateQuery= strict'	Both	link	Issues are included in the response where the user has: Browse projects project permission for the project containing the issue. If issue-level security is configured, issue-level security permission to view the issue.
Get all statuses for a project	GET /rest/api/latest/ project/ {projectKey}/ statuses	Both	link	Browse Projects project permission for the project.
Get project	GET /rest/api/latest/ project/ {projectKey}? expand=issueTypes	Both	link	Browse Projects project permission for the project.
Get issue	GET /rest/api/latest/ issue/{issueNumber}	Both	link	Browse projects project permission for the project that the issue is in. If issue-level security is configured, issue-level security permission to view the issue.
Get fields	GET /rest/api/latest/ field	Both	link	None
Get link types	GET /rest/api/latest/ issueLinkType	Both	link	Browse projects project permission for a project in the site.
Add issue link to issue	POST /rest/api/latest/ issueLinkType	Both	link	Browse project project permission for all the projects containing the issues to be linked, Link issues project permission on the project containing the from (outward) issue, If issue-level security is configured, issue-level security permission to view the issue. If the comment has visibility restrictions, belongs to the group or has the role visibility is restricted to.
Get remote links for issue	GET /rest/api/latest/ issue/{issueNumber}/ remotelink	Both	link	Browse projects project permission for the project that the issue is in. If issue-level security is configured, issue-level security permission to view the issue.
Add remote link to issue	POST /rest/api/latest/ issue/{issueNumber}/ remotelink	Both	link	Browse projects project permission for the project that the issue is in. If issue-level security is configured, issue-level security permission to view the issue.