Web API
- Takafumi Ohtake (Deactivated)
About Web API
Secure Custom Fields for Jira stores field values into Jira issues. The values are encrypted to prevent not permitted users from reading and editing values.
However, if you want to use secure field values in other systems, you can’t use Jira REST API because of the encrypted values. The app provides its own API to make it possible. The API is like Jira REST API while it returns decrypted values.
WARNING
This is a beta feature. Please note,
The web API works with the app's privilege. It means web API ignores all permissions including field-level permission, issue security, and Jira standard permissions.
So, restricting token scope for every token on this screen is strongly recommended.The web API would make breaking changes in the future.
How to enable and call Web API
Enable the Web API, then get url and token
Go to the Secure Custom Fields settings page.
Click Web API Settings.
Click the Create New Token button.
(Optional) Set the name and scope of the token.
Uncheck the Mask token checkbox.
Get Endpoint URL and Token to call Web API.
Call the Web API
The API requires you basic authentication.
The credential is the app’s own one. Do not use your Jira account credential.
Username is always “admin“which is not an actual user name. Password is the token you created on the config page.
If you use cURL, you can call the API like below.
curl -u admin:<token> --header 'Accept: application/json' https://485bab7c-71c8-4bd7-bd7a-9e2bca87152b.hello.atlassian-dev.net/x1/<some_text>?issue=TEST-1
APIs
Get issue
Returns all secure field values of an issue.
Request
Http method | GET |
URL | As Endpoint URL |
Query parameters |
|
Sample
curl -u admin:<token> --header 'Accept: application/json' https://485bab7c-71c8-4bd7-bd7a-9e2bca87152b.hello.atlassian-dev.net/x1/<some_text>?issue=TEST-1Response
Status code |
|
Content type | application/json |
Body | {
"id": "10001", <- the id of the issue
"key": "TEST-1", <- the key of the issue
"fields": { <- all secure field values of the issue
"customfield_10071": "multi\nline\ntext", <- Secure Text Field (multi-line)
"customfield_10076": "text", <- Secure Text Field (single line)
"customfield_10077": "2021-10-09", <- Secure Date Field
"customfield_10078": 1234.5678, <- Secure Number Field
"customfield_10079": { <- Secure Select List (single choice), Secure Radio Buttons
"id": "5",
"value": "Apple"
},
"customfield_10080": [ <- Secure Select List (multiple choices), Secure Checkboxes
{
"id": "2",
"value": "Brother"
}
],
"customfield_10081": { <- Secure User Picker (single)
"accountId": "xxxx",
"displayName": "Tom Watson"
..... other properties in the response of https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-get
},
"customfield_10082": [ <- Secure User Picker (multiple)
{
"accountId": "yyyy",
"displayName": "Emil Prim"
..... other properties in the response of https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-users/#api-rest-api-3-user-get
}
],
"customfield_10083": null
}
}
|
Edit issue
Update secure field values of an issue.
Request
Http method | PUT |
URL | As Endpoint URL |
Query parameters |
|
Body | {
"fields": { <- fields you want to update a value
"customfield_10071": "multi\nline\ntext", <- Secure Text Field (multi-line)
"customfield_10076": "text", <- Secure Text Field (single line)
"customfield_10077": "2021-10-09", <- Secure Date Field
"customfield_10078": 1234.5678, <- Secure Number Field
"customfield_10079": {"id": "5"}, <- Secure Select List (single choice), Secure Radio Buttons
"customfield_10080": [{"id": "2"}], <- Secure Select List (multiple choices), Secure Checkboxes
"customfield_10081": {"accountId": "xxxx"}, <- Secure User Picker (single)
"customfield_10082": [{"accountId": "yyyy"}], <- Secure User Picker (multiple)
"customfield_10083": null <- clear value
}
} |
Sample
Response
Status code |
|
Troubleshooting
Trouble | Solution |
|---|---|
API returns 404(Not found) when the issue exists. Or API returns 400(Bad Request) when editing issues. | The API work with the app's privilege. The permission scheme or issue security level may hide the issue from the app. Please check permission scheme and issue security scheme.
|