This API is dedicated to programmatic integration between Jira and third-party systems, Jira automation, or workflow when JWT is not feasible. In order to authenticate calls please setup a personal access token as described .
Three request headers must be set beforehand:
email - email address of the user, who will be accessing API
jira-host - address of Jira Cloud instance
api-token - token created by the user who will be accessing the API
Get Value This endpoint allows to get all Secure field values for the given issue. Only users with READ permission can see the secure values.
Parameters
issueId - id of the issue OR issue key.
Response example
[
{
"fieldName": "Secure Number field",
"fieldType": "SECURE_NUMBER",
"globalConfigurationId": "64d25ee1ae45d1595276f16a",
"textFieldValue": null,
"numberFieldValue": 7654.0,
"date": null,
"permissions": {
"EDIT": true,
"VIEW": true,
"HISTORY": true
},
"required": false
}
]
Update Value
POST /integration/app/rest/api/v1/secure-field/value/{issueId}
Endpoint updates all Secure field values for the given issue. Only users with WRITE permission can update values.
GlobalConfigurationId of the Secure field is required and can be obtained by using a GET endpoint described above.
Parameters
issueId - id of the issue OR issue key.
Request body
Fields with value are mapped to:
textFieldValue - Secure Text Single Line, Secure Text Multi Line
numericFieldValue - Secure Number
- Secure Date in format "yyyy-MM-dd"
dateTimeFieldValue - Secure Date Time in format "yyyy-MM-dd'T'HH:mm:ss.SSSZ".
Request body example:
[
{
"globalConfigurationId": "64d25ee1ae45d1595276f16a",
"numberFieldValue": 500
}
]
Response example
[
{
"globalConfigurationId": "64d25ee1ae45d1595276f16a",
"textFieldValue": null,
"numberFieldValue": 500.0,
"dateFieldValue": null,
"dateTimeFieldValue": null
}
]
Get History
GET /integration/app/rest/api/v1/secure-field/history/{issueId}
Get Secure fields history records. Only users with HISTORY permission can access the records.
Parameters
issueId - id of the issue OR issue key.
page - number of a page
size - number of items on a page
Response example
{
"total": 2,
"page": 0,
"pageSize": 10,
"issueId": "10008",
"items": [
{
"authorId": "5e8f9de61c07ed0b7df4063c",
"secureFieldId": "64d25ee1ae45d1595276f16a",
"secureFieldName": "Secure Number field",
"oldValue": "7654.0",
"newValue": "500.0",
"created": 1691509448914
},
{
"authorId": "5e8f9de61c07ed0b7df4063c",
"secureFieldId": "64d25ee1ae45d1595276f16a",
"secureFieldName": "Secure Number field",
"oldValue": null,
"newValue": "7654.0",
"created": 1691508486073
}
]
}
Search for secure fields
POST /integration/app/rest/api/v1/secure-field/search
The endpoint allows the searching of issues based on secure field values.
Only users with READ permission can utilise the endpoint.
JQL operators The availability of search operators varies depending on the type of secure field:
Number fields: NOT_EMPTY, EQUALS (=), NOT_EQUALS (!=), LESS (<), LESS_EQUAL (<=), GREATER (>), GREATER_EQUAL (>=)
Text fields: NOT_EMPTY, EQUALS (=), NOT_EQUALS (!=), CONTAIN (~), NOT_CONTAIN (!~)
Date fields: NOT_EMPTY, EQUALS (=), NOT_EQUALS (!=), LESS (<), LESS_EQUAL (<=), GREATER (>), GREATER_EQUAL (>=)
Group fields: NOT_EMPTY, IN, NOT_IN List fields: NOT_EMPTY, IN, NOT_IN User fields: NOT_EMPTY, IN, NOT_IN. Multiple criteria can be connected using AND operator.
Sorting order can be ASC or DESC.
Request body
UI vs. REST call examples for different secure field types:
Secure number
UI REST
{
"projectId": "10076",
"page": 0,
"numberOfIssuesOnPage": 10,
"sort": {
"sortField": "Secure Number",
"order": "ASC"
},
"criteriaList": [
{
"customFieldId": "65dc98d4e255414216469654",
"operator": "GREATER",
"value": 5
}
]
}
Secure text
UI REST
{
"projectId": "10076",
"page": 0,
"numberOfIssuesOnPage": 10,
"sort": {
"sortField": "Secure Text (multi-line)",
"order": "ASC"
},
"criteriaList": [
{
"customFieldId": "66cccbfa6abc1c0d56fe087d",
"operator": "CONTAIN",
"value": "localhost"
}
]
}
Secure date
UI REST
{
"projectId": "10076",
"page": 0,
"numberOfIssuesOnPage": 20,
"sort": {
"sortField": "Secure Date Picker",
"order": "ASC"
},
"criteriaList": [
{
"customFieldId": "66cccbfa6abc1c0d56fe086d",
"operator": "LESS_EQUAL",
"value": "2024-09-01"
}
]
}
Secure group
UI REST
{
"projectId": "10076",
"page": 0,
"numberOfIssuesOnPage": 30,
"criteriaList": [
{
"customFieldId": "65dc98d4e25541421646964c",
"operator": "NOT_IN",
"value": "b8a78765-cea8-4a32-ad10-e7df715275ca"
}
]
}
Secure list
UI REST
{
"projectId": "10076",
"page": 0,
"numberOfIssuesOnPage": 30,
"criteriaList": [
{
"customFieldId": "65dc98d4e25541421646964a",
"operator": "NOT_EMPTY"
}
]
}
Secure user
UI REST
{
"projectId": "10076",
"page": 0,
"numberOfIssuesOnPage": 10,
"criteriaList": [
{
"customFieldId": "66cccbfa6abc1c0d56fe0875",
"operator": "IN",
"value": "712020:51f069c5-053b-4b73-bc53-cf645e017ab7"
}
]
}
Request structure
projectId* Id of the project to search within string (example: 10000 ) page the number of the search result page to be shown integer (example: 0 ) numberOfIssuesOnPage number of the issues to be displayed per page integer (example: 20 ) sort sorting the search results by the field criteriaList* list of search criteria customFieldId* Id of the secure field to search string (example: 65f8a3f0be05d471ce104803 ) operator* JQL search operator string (example: LESS_EQUAL ) value* the specific secure field's value to search against (example: 5 ) jqlFilter (optional) JQL filter to narrow the search string (example: created >= -30d ) sessionId unique session Id in UUID4 format generated by the user. Required for performance optimization when loading multiple pages. string (example: c769436b-76a0-4d2e-bed3-47aaa0790eab )
Response example
[
{
"projectId": "10007",
"issueId": "13243",
"issueKey": "SGS-3176",
"issueTypeId": "10004",
"summary": "Story 2.0",
"secureFieldValues": {
"65f8a3f0be05d471ce104803": "70.0"
},
"secureFieldMetaData": {
"65f8a3f0be05d471ce104803": {
"customFieldId": "65f8a3f0be05d471ce104803",
"customFieldName": "Secure Number",
"issueTypeIds": [
"10000",
"10004",
"10005",
"10006",
"10007"
],
"fieldType": "SECURE_NUMBER",
"options": []
}
}
}
]
Responses 200 - OK. Returned if the request is successful.
401 - Unauthorized.
403 - Forbidden. Returned if the user does not have permission to complete this request.
404 - Not Found. Returned if the issue does not exist.
500 - Server Error.