App Configuration

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


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.


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


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:

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:

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:

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.

  • 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

IP Address Restrictions

Admins may restrict REST API requests by IP- addresses or ranges. This restriction will apply to both token- and password authentication,
should the latter not have been disabled (see next section). 

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 Basic Auth with passwords

You may want to disable password authentication for REST endpoints completely. Should the token provided not match any user's tokens,
a 403 status code will be returned. With Basic Auth and user passwords enabled, Jira will try to authenticate the user by password, provided that it is correct.


When playing and testing with wrong passwords or tokens, be aware that this can lead to too many failed logins recorded.
Go to your user manager and reset the failed login count for the user you are testing with.


Audit Logging

Since version 1.1.0, creating and deleting tokens (both deleting a single token or all for a user as an admin)
will cause an audit log record being created in Jira (https://your-jira/auditing/view) or Confluence (https://your-confluence/admin/auditlogging.action).
This become especially important, when an admin creates a token on behalf of some other user or just in general, to trace API Token usage.


After changing the log level for the package de.resolution.apitokenauth to INFO
Jirahttps://your-jira/secure/admin/ViewLogging.jsparead here on how make the log level persistent
Confluencehttps://your-confluence/admin/viewlog4j.actionread here on how make the log level persistent

you'll see two authentication related entries in the log file of Jira or Confluence, containing a description of the event,
the username and the path of the REST endpoint for the call. 

2020-04-15 07:25:04,213+0000 http-nio-8080-exec-4 INFO anonymous 445x4051x1 -, /rest/de.resolution.apitokenauth/latest/user/tokensByFilter [d.resolution.apitokenauth.ApiTokenAuthenticationService] Found a matching token for authenticating user admin, created on 1586935495716.
REST endpoint: /rest/de.resolution.apitokenauth/latest/user/tokensByFilter


2020-04-15 07:27:40,607+0000 http-nio-8080-exec-23 INFO anonymous 447x4055x1 -, /rest/de.resolution.apitokenauth/latest/user/tokensByFilter [d.resolution.apitokenauth.ApiTokenAuthenticationService]
User admin tried to authenticate with an invalid token or a regular password. Passing the request further to the default authenticator. REST endpoint: /rest/de.resolution.apitokenauth/latest/user/tokensByFilter