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 AuthenticationBitbucketOpen the admin settings via the top right corner icon and click on one of the API Token Authentication linksPermissions & 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 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 sectionYou 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 Authentication with Session CookiesEnabling this option will render any session invalid after using it for one request. While this can be considered more secure, it comes with the downside of not being able to use sessions for subsequent request, such as using it to download attachments as described here.You also won't be able to use sessions retrieved during authentication on the Jira session endpoint anymore.With that option we provide the same as Atlassian is doing already in Cloud.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.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. SAML Single Sign-On is available for Atlassian Server & Atlassian Data Center products. Our Jira Data Center, Confluence Data Center, Bitbucket Data Center, Jira Server, Confluence Server, Bitbucket Server and other apps are all available on the Atlassian Marketplace.