App Configuration

Administrators can adjust the app settings in the corresponding management section.

Jira

In Jira, navigate to the User management section and select API Token Authentication
The System-Wide Settings and the Permission tabs provide all settings and options to control the app.

Confluence

In Confluence, scroll down to the Users & Security section in the administration configuration panel and select API Token Authentication

Bitbucket

Open the admin settings via the top right corner icon and click on one of the API Token Authentication links


Permissions & Token Scopes

Since version 1.3.0 administrators have more control about the following permissions and can assign one or multiple groups to each:

  • Use Tokens 
  • Create Tokens for yourself
  • Create Tokens for other users

These settings can be found in the permission tab:

Token Scopes

Since version 1.5.0, users with the "Create Token On Behalf Permission" can assign scopes to the tokens they create for other users.
For regular users with the "Create Token Permission", administrators can limit these tokens to always be Read Only tokens by checking
the corresponding box in the "Create Token Permission" section:



Read more about these scopes below. 

Read Only

Only the GET, HEAD and OPTIONS HTTP request types are allowed, using a token on endpoints requiring any other type will result in a 403 Forbidden error.
There are two exceptions/ endpoints not affected by that:

  • the Jira Session endpoint to which you can POST your username and token to retrieve a session cookie
  • the API Token Authentication endpoint to which a user can POST details to create a token, if permitted to

Read & Write

All HTTP request types are allowed to be used.
Every type other than GET, HEAD and OPTIONS suggests that it is a write operation somehow, manipulating existing data in some way.

If your configuration wasn't migrated from an earlier version, in which you might have restricted creating- and using tokens to administrators only,
the default settings allow all users to create- and use their own tokens and administrators to do that for other users.

You can change that and add one or more groups to each of these permissions after unchecking the "Allow everyone ... " checkboxes:

Please note that there is a misleading description below the Groups with create token on behalf permission picklist,
suggesting that there is checkbox allowing everybody to receive that permission. This will be corrected/ removed in an upcoming release.

Depending on your changes, you might see some warnings and recommendations.
These are of informational character only and won't prevent you from saving the settings.


If you remove a permission for a user's group again, the API Token Authentication link will be removed from their top right user settings picker
(see User Guide) and if they would browse the page manually, users will see an info box instead:

 If you remove a permission for a user's group again, the API Token Authentication link will be removed from their top right user settings picker

Trying to create a token from a page still open will result in a 403 Forbidden:

System-Wide Settings

The app contains a few System-Wide Settings settings, available for administrators only. 
Settings here apply to all users accessing the REST API with Basic Authentication and any of the tokens they've created for their user in Jira or Confluence.
Please find more details about the options currently available below.

Token Validity Time

Administrator can define a maximum validity time of a token, if required.


Options are:

  • Never
  • 1 to 6 months
  • 1 year
  • 2 years

Users may override this according to the boundaries allowed.
Examples:

  • System Wide Setting is 6 month - users can select 6 month only, nothing else
  • System Wide Setting is 1 year - users can select 1 year or 6 month, nothing else
  • System Wide Setting is 2 years - users can select 2 years, 1 year or 6 month, nothing else
  • System Wide Setting is Never - users can select any validity time from the select list

Since version 1.5.0 it is possible to pass a custom ISO 8601 date-time string to set a specific expiration date time within the boundaries allowed.
Read more about it here


IP Address Restrictions

Admins may restrict REST API requests by IP- addresses or ranges.
Here is what happens, if the request comes from an IP address not allowed:

  • Authentication with API Token and Basic Authentication with User Password enabled (see chapter further below)
    • Error 401 (the request needs to be passed to the Atlassian Authenticator,
      because it could potentially be a password and since the token won't be one, a 401 is returned by the Atlassian Authenticator)

  • Authentication with API Token and Basic Authentication with User Password disabled (see chapter further below)
    • Error 401 with a message containing the IP address not allowed



Just enter one or more addresses or address ranges with the + button or delete existing ones and save your settings.


(info) If no addresses were provided, requests from every IP address will be allowed.

IP Restrictions & Reverse Proxy

The above example will only work, if you are not running Jira or Confluence behind a reverse proxy, as the client IP address is contained in a different header.
Since version 1.4.0 you can enable reverse proxy support.

Enable it by checking the corresponding box and add one or more trusted reverse proxy IP addresses or ranges:

You might also need to adjust the header name to read the client IP from, usually X-Forwarded-For or X-Real-IP:


If you need to find out why you can't access the REST API after applying IP restrictions, please read our troubleshooting guide:
Troubleshooting IP range restriction issues

Disable Personal Access Tokens

This feature is only visible in Jira starting with version 8.14 and in Confluence starting with version 7.9, since these versions come with the Personal Access Token app. It is always visible in Bitbucket.

If you are running our app, you should disable it. For obvious reasons, it doesn't make sense to run both in parallel, especially because the app from Atlassian does not offer any token scope or other permission based settings.
Users could then create tokens with the Atlassian app and perform write operations, which they were not allowed to in our app's config.

You can do that with the button in the Jira/ Confluence/ Bitbucket Personal Access Tokens section

You can do this in the app management section (https://your-jira-bitbucket-or-confluence-url/plugins/servlet/upm/manage/system) as well.
If you've uninstalled our app and want to re-enable it, you can only do that from there, unless you didn't enable it already before uninstalling ours.


Disable Basic Auth with Passwords 

You may also want to disable password authentication for REST endpoints completely. Should the token provided then not match any user's tokens,
a 401 status code will be returned. With Basic Auth and user passwords enabled, Jira, Confluence or Bitbucket will try to authenticate the user by password.

Since version 1.5.0 there is a new checkbox with which you can prevent path traversal in REST URLs.
That way you can avoid users getting a session with a password and Basic Auth on a non-REST URL.
This option is only available, if Basic Authentication with User Password is checked.

Confluence Only  -  Allow Basic Authentication With Passwords on the Confluence Remote API (XML-RPC & SOAP)

The Confluence Remote API can't be used with API Tokens but is sometimes required, since not every method has been implemented in REST.
Since version 1.6.2, Confluence admins can make an exception, so that even though Basic Authentication with passwords is disabled in general, it would still work on the Remote API.


Pitfalls

When playing and testing with wrong passwords or tokens, be aware that this can lead to too many failed logins recorded.
Read more about it in our knowledge base.