API Token Authentication Documentation Current: Admin Guide Admin Guide App ConfigurationAdministrators can adjust the app settings in the corresponding management section.JiraIn Jira, navigate to the User management section and select API Token AuthenticationThe System-Wide Settings and the Permission tabs provide all settings and options to control the app.ConfluenceIn Confluence, scroll down to the Users & Security section in the administration configuration panel and select API Token AuthenticationPermissions & Token ScopesSince 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 yourselfCreate Tokens for other usersThese settings can be found in the permission tab:Token ScopesSince 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 checkingthe corresponding box in the "Create Token Permission" section:Read more about these scopes below. Read OnlyOnly 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 cookiethe API Token Authentication endpoint to which a user can POST details to create a token, if permitted toRead & WriteAll 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:Trying to create a token from a page still open will result in a 403 Forbidden:System-Wide SettingsThe 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 TimeAdministrator can define a maximum validity time of a token, if required.Options are:Never1 to 6 months1 year2 yearsUsers may override this according to the boundaries allowed. Examples:System Wide Setting is 6 month - users can select 6 month only, nothing elseSystem Wide Setting is 1 year - users can select 1 year or 6 month, nothing elseSystem Wide Setting is 2 years - users can select 2 years, 1 year or 6 month, nothing elseSystem 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 RestrictionsAdmins 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 allowedJust enter one or more addresses or address ranges with the + button or delete existing ones and save your settings. If no addresses were provided, requests from every IP address will be allowed.IP Restrictions & Reverse ProxyThe 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 passwordsYou 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.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.PitfallsWhen 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.