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 or 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,

  • It will make breaking changes in the future. If you can't allow it, you shouldn't use it.

  • Web API of the app works with the app's privilege. It means web API ignores all permissions including field-level permission, issue security, and Jira standard permissions. So, you must NOT share web API with not Jira administrators.

How to enable and call Web API

Enable the Web API and get url and token

  1. Go to the Secure Custom Fields settings page.

  2. Click Web API Settings.

  3. Click the Create New Token button.

  4. Uncheck the Mask token checkbox.

  5. 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 real Jira accounts credential.
Username is always “admin“which is not a real 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
curl -u admin:<token> --header 'Accept: application/json' https://485bab7c-71c8-4bd7-bd7a-9e2bca87152b.hello.atlassian-dev.net/x1/<some_text>?issue=TEST-1
CODE

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

{
    "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": null
    }
}
CODE

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

{
    "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": null                  <- clear value
    }
}
CODE
Sample
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
          }
     }'
CODE

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.