Web API

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	issue `required` The ID or key of the issue.

Sample

CODE

curl -u admin:<token> --header 'Accept: application/json' https://485bab7c-71c8-4bd7-bd7a-9e2bca87152b.hello.atlassian-dev.net/x1/<some_text>?issue=TEST-1

Response

Status code

200
- Reauest is successful.
400
- Required parameters are missing.
401
- Credential is missing.
403
- Credential is invalid.
404
- Issue is not found. If the issue exists, please see the troubleshooting section below.

Content type

application/json

Body

CODE

{
    "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	issue `required` The ID or key of the issue.
Body	CODE { "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

CODE

curl -u admin:<token> \
     -X PUT \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --url https://485bab7c-71c8-4bd7-bd7a-9e2bca87152b.hello.atlassian-dev.net/x1/<some_text>?issue=TEST-1 \
     --data '{
          "fields": {
             "customfield_10077": "2021-10-09",
             "customfield_10079": null
          }
     }'

Response

Status code

204
- Reauest is successful
400
- Required parameters are missing.
- Request body is missing or not invalid.
- Field has not configured yet.
- The app doesn’t have edit permission. Please see the troubleshooting section below.
401
- Credential is missing.
403
- Credential is invalid.
404
- Issue is not found. If the issue exists, please see the troubleshooting section below.

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.

Permission scheme
- “Browse Projects” and “Edit Issues“ permissions has to contain “atlassian-addons-admin“ group.
Issue security scheme
- Issue security levels have to contain “atlassian-addons-admin“ group.