Since version 1.8.1 users can now test and verify whether authentication with an API token is successful or not and get some details in the latter case.

Using the test endpoint

Please use the following REST endpoint:

https://<your-jira-confluence-or-bitbucket-base-URL>/rest/de.resolution.apitokenauth/latest/user/authTest
BASH

Requests can be of type GET, PUT or POST and must contain a valid Basic- or Bearer authentication header, same as if you'd authenticate on any other REST endpoint.

You should not use the endpoint in a browser.
The request will not contain the expected authorization header and thus always show a failure result.
It will also invalidate the session you might have already when logged in to Jira, Confluence or Bitbucket and you'd need to log in again.


Examples

Basic Auth

The following examples are using GET as a request type. Please read here for PUT and POST.
Modify the following curl call to use your instance URL and replace the <username> with yours. Execute it and you'll be prompted for the API token.

curl --location --request GET 'https://<your-base-URL>/rest/de.resolution.apitokenauth/latest/user/authTest' -u <username>
BASH

A successful result will look like this:

{
  "isSuccessfulAuthentication" : true
}
BASH

Authentication failures will result in responses containing an authenticationFailureDetails field.

Tokens invalid, revoked or expired

In the simplest case, the token is not valid or not valid anymore:

{
  "isSuccessfulAuthentication" : false,
  "authenticationFailureDetails" : "Token is invalid, has been revoked or expired"
}
BASH

Permission related failures

You might also not have the permission (anymore) to use tokens:

{
  "isSuccessfulAuthentication" : false,
  "authenticationFailureDetails" : "You are not permitted to use API tokens"
}
BASH

IP restrictions

Your client IP could not be in the range of IP addresses allowed to make requests with a token:

{
  "isSuccessfulAuthentication" : false,
  "authenticationFailureDetails" : "IP address 100.112.0.11 not permitted"
}
BASH

Malformed or missing authentication header

The curl example above already constructs the authentication header for you. You can also pass that header in the request:

curl --location --request GET 'https://<your-base-URL>/rest/de.resolution.apitokenauth/latest/user/authTest' --header 'Authorization: Basic'
BASH

If it's malformed the endpoint will tell you that:

{
  "isSuccessfulAuthentication" : false,
  "authenticationFailureDetails" : "No valid bearer- or basic auth header present"
}
BASH

A valid Basic authentication header must not only contain the type but the Base64 encoded username, colon and API token (read here please).
The valid example looks like this:

curl --location --request GET 'https://<your-base-URL>/rest/de.resolution.apitokenauth/latest/user/authTest' --header 'Authorization: Basic dGhlbzpVcXhBVWZEYnlRaUQ4SDdLNXF4YUpBZDN1VlEyUVJialRnRDdnZg=='
BASH

Bearer Auth

All the above examples are also valid for Bearer authentication. The difference is only the curl call. For Bearer authentication you only need to pass the API token in the authentication header in plain text:

curl --location --request GET 'https://<your-base-URL>/rest/de.resolution.apitokenauth/latest/user/authTest' --header 'Authorization: Bearer <your-api-token>'
BASH

The responses will be the same as above in case of failure.

Testing PUT and POST requests

The endpoint also accepts PUT and POST requests:

curl --location --request POST 'https://jobo-jira-sd.klab.resolution.de/rest/de.resolution.apitokenauth/latest/user/authTest' -u <username> \
--header 'Content-Type: application/json' \
--data-raw '{"just a test"}'
BASH

It would result in failure should the token be of read-only scope:

{
    "isSuccessfulAuthentication": false,
    "authenticationFailureDetails": "The token scope is read-only and only covers GET, HEAD and OPTIONS requests. Request method type was POST."
}
BASH

Disabling the test endpoint

Administrators can turn the endpoint off at the bottom of the System-Wide settings tab of the configuration:

Everybody trying to use it will get the following result:

{
  "testEndpointUnavailable" : "The test endpoint has been disabled by an administrator"
}
BASH

Miscellaneous

Sessions

The test endpoint will never create and return any session and will also invalidate the session you might currently have in the terminal from which you are executing the test.
If you are using Postman or another REST client the same will happen.

Bitbucket and Captcha Challenge

If you are trying to authenticate with an invalid, revoked or expired token Bitbucket will prompt for entering CAPTCHA after failing to authenticate 5 times in a row.
The endpoint will also tell you about it:

For security reasons you must answer a CAPTCHA question.
BASH

Your administrator could clear the captcha counter for you but the easiest way is just to log in with your user and password into the Bitbucket UI.