General information

A primary use case for API tokens is to allow scripts to access REST APIs for Jira applications using HTTP basic authentication.

If you define a token for a user, only that user can use it. If you do not specify a user, any user will be able to use this token.

If an external system is compromised, you can revoke the token instead of changing the password and consequently changing it in all scripts and integrations.

You can generate the code snippet (JavaScript/curl) and authentication data for calls by clicking icon

If you want to check who used the token and when, all calls are added to the audit log

Specify limits for tokens

You can restrict the token to specific specific methods (GET, POST, PUT, DELETE, etc.), URL's, URL parameters, and JSON data in the body.

Token restrictions for URLs, URL parameters, and JSON data in the body handling definition with regular expressions.

URL without any other restrictions

Example:

• Restriction to JRA project issues

.*/rest/api/2/issue/JRA.*

URL with POST method restriction

Example:

• Restriction to 'comment' endpoint on KANBAN-100 issue (only POST method)

[post].*/rest/api/2/issue/KANBAN-100/comment.*

URL with parameters

Add an additional definition to the end of the “Limit to” definition as shown in the example

[QueryParam::URL_PARAM_NAME==REGEXP]

• where URL_PARAM NAME is the name of the URL parameter

• where REGEXP is the definition of a regular expression, what value the URL parameter can take

Example:

• Restriction to all filters for all users (only with permission)

.*/rest/extender/1.0/filter/user/.*[QueryParam::permissions==true]

• Restriction to worklogs for all users (only in the date range 2018-01-01 - 2018-12-01)

.*rest/extender/1.0/worklog/user/.*[QueryParam::dateFrom==2018-01-01][QueryParam::dateTo==2018-12-01]

URL with JSON data in the body

Add an additional definition to the end of the “Limit to” definition as shown in the example

[JsonData::JSON_NODE_NAME==REGEXP]

• where JSON_NODE_NAME NAME is the name of the JSON node name

• where REGEXP is the definition of a regular expression, what value the JSON node name can take

Example:

{
    "name": "All Open Bugs",
    "description": "Lists all open bugs",
    "jql": "type = Bug and resolution is empty",
    "favourite": true,
    "editable": false
}

• Restriction to create new filter (limited to uneditable only)

.*/rest/api/2/filter[JsonData::editable==false]

• Restriction to create new filter (limited to uneditable only without adding to favorites)

.*/rest/api/2/filter[JsonData::editable==false][JsonData::favourite==false]

Secure mode

We created this mode to add another layer of security to your tokens and allow you to better protect them.

Standard mode	Secure mode

How to turn on Secure mode

⚠  Keep in mind that this setting is universal across Jira and will require shutting down the instance. As always, we recommend testing changes in a lower environment before attempting them in production.

1. Shutdown Jira. Even on Jira Data Center, it is necessary to shutdown all nodes. A rolling restart of the nodes won't suffice.

2. Edit the jira-config.properties file in your JIRA application home directory.

   •  See Making changes to the jira-config.properties file for more information.

3. Change the value of the ops.bar.group.size.opsbar-classic-transitions-view property within this file to be the number of transition buttons required before the Workflow menu.

4. If this property does not appear in the jira-config.properties file, add it

   extender.token.secure.mode = true

5. Save the updated jira-config.properties file.

6. Restart JIRA. 

How does it work

Depending on the details of the HTTP library you use, simply replace your password with the token. For example, when using curl, you could do something like this:

curl -v https://my-jira.com --user USER:TOKEN

Note that:

• USER here is the email address or user name.

• TOKEN here is token generated in Extender REST API Tokens page

CURL Example

curl -s -u admin:token1234567890 JIRA_URL/rest/api/2/issue/AAA-1

curl -s -u ansible@ansible.jira.pl:token0987654321 JIRA_URL/rest/api/2/issue/AAA-1

curl -u admin:token0987654321 -H "Content-Type: application/json" 
--data '{"body":"Comment text"}' -X JIRA_URL/rest/api/2/issue/ISSUE-1/comment

JavaScript Example

var base64 = atob("USERNAME:TOKEN");
$.ajax({
  "url": "http://localhost:2990/jira/rest/api/2/issuetype",
    "headers": {
    "Authorization": "Basic " + base64
  }
}).done(function (response) {
  console.log(response);
});

var base64 = atob("USERNAME:TOKEN");
var headers = new Headers();
headers.append("Authorization", "Basic " + base64);

fetch("http://localhost:2990/jira/rest/api/2/issuetype", {"headers": headers})
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Postman Example

Note that :

• Basic Auth use this type in Authorization type

• Username here is the email address or user name.

• Passwordhere is token generated in Extender REST API Tokens page

Changes