REST API
The API Token Authentication app currently provides a few REST API endpoints. Please find below a summary of what can be done already.
Create a new token
Create a new token by providing its description as follows. The response will contain the token automatically generated.
You could also provide an expiration period in months, provided that it is smaller or equal to the one defined by the administrator in the system-wide settings.
In the below example, a token with an expiration time of just one month is created:
Creating tokens with a specific expiration date
Since version 1.5.0 you may also pass an ISO 8601 date-time string for the tokenExpirationDateTime field in the payload.
Please note that it must be below or equal to the maximum allowed value set by your administrator. If not, you'll get a 400 error with some details:
Otherwise, it will return the token response. Please note that tokenValidityTimeInMonths is not important then, but tokenExpirationDateTime and tokenExpirationDateTimeMillis instead.
You need to include the offset to UTC in that string so that the expiration time works as expected in the user's time zone.
You could validate the expiration date time by reviewing it again in your token list:
Update a token description
This will only succeed for users in groups with the Create Token Permission or Create & Delete Token On Behalf Permission assigned to it. Updating the description of another user's token will only work for users in a group with the Create & Delete Token On Behalf Permission. Here's more on the topic of permissions.
List all tokens
To get an overview of what tokens you've added for your user and to grab an ID of one to update or delete it, execute the request below.
You may omit the pipe symbol and python command at the end, it is just for beautifying the JSON response.
which produces output like:
List all tokens (all users)
The REST endpoint to retrieve token details for all users is only accessible for users with the Create & Delete Token On Behalf Permission. Please read more about permissions here.
You can also use the filter parameters described here to filter for specific properties.
To get an overview of all tokens in the system (including the expired ones) and to grab an id of one to update or delete it, execute the request below. You may omit the pipe symbol and python command at the end, it is just for beautifying the JSON response.
which produces output like:
Delete a token
Grab a token ID retrieved with the previous call and put it to end of the call:
Administrative REST API Methods
Since version 1.1.0, sys admins may use the endpoints below as well
Create Tokens for other Users
Admins may create tokens for other users by providing their user key in the request payload. If no token validity time is provided, the system default will be used. How to get a key for a user in Jira/ Confluence is explained in the previous chapter.
If a token validity time is provided, it will be validated and adjusted to the value set in the system-wide settings, if required. This prevents again trying to keep a token valid forever or for 12 months, where only 6 are allowed.
Delete all tokens for a user
This call will work for sysadmins only and otherwise throw 403. Please note that the user key is passed, not the username *.
Get User Key for a User
* you can get a user's key by using the REST API as an admin
The result will contain a key or userKey field (Jira or Confluence)
Jira
Confluence
Get User Key by E-Mail
Since version 1.5.0 users with the Create Token On Behalf Permission can use a REST endpoint which allows them to retrieve a user key by providing an e-mail address of a user.
If this address is valid and unique (only assigned to a single user), the endpoint will return the user key.
Response if not a single user has the email address
Response if the email address has been assigned to more than one user:
Filter User Tokens
Since version 1.3.0, the Token Manager tab (read the Token Manager section here) provides an easy-to-use interface for almost all purposes.
There is also a REST endpoint to filter for tokens, i.e. to remind users about their tokens soon to expire, with a custom integration.
We are planning to integrate notifications for tokens to expire soon in a future release.
Filter parameters
Parameter | Value | Comment |
---|---|---|
userFilter | valid user key | read above how to get a user key for a name or by email address; if you want to filter for more than one user, repeat that parameter for as many users you want to filter for |
descriptionFilter | search term | string to search for in all token descriptions |
notValidAfter | epoch Unix timestamp | tokens not valid anymore after that date/ time in milliseconds |
tokenScope | integer | 0 = no scope (all pre 1.5.0 tokens), 1 = read-only, 2 = read/ write |
fromCreated | epoch Unix timestamp | |
untilCreated | epoch Unix timestamp | |
fromLastUsed | epoch Unix timestamp | |
untilLastUsed | epoch Unix timestamp | |
fromExpiresDuring | epoch Unix timestamp | |
untilExpiresDuring | epoch Unix timestamp |
Below is an example of all the above parameters but the notValidAfter parameter
Retrieve all tokens not valid after a certain time
The below examples show how to receive all tokens not valid anymore after a certain date/ time in milliseconds
Instead of passing a timestamp as parameter value for notValidAfter, you can also send -1 which will return all tokens
And returns
The results are paged and you may only retrieve 50 results max per page. Below another example with paging:
Don't forget to wrap the URL in double quotes, when doing that on the command line, as the & would be interpreted as sending the process into the background
The output would look like the below and contain links to the previous and next page, if available.
Get Email Addresses For Users
The output contains the user key as a unique user identifier. If you need to retrieve the username or email for the user, you need to call the Atlassian REST API:
Jira
Confluence
Unfortunately, the Confluence REST API doesn't return the email address for a user https://docs.atlassian.com/ConfluenceServer/rest/7.12.0/#api/user-getUser,
not even as a property which could be expanded.
REST API Error Response Codes
REST Endpoint | Action | HTTP Result Code |
---|---|---|
Regular REST endpoints with the API Token app enabled and Basic Auth with password still allowed | User accesses the endpoint with a token expired or wrong | 401 |
Regular REST endpoints with the API Token app enabled and Basic Auth with password disabled | User accesses the endpoint with a token expired or wrong | 401 |
Regular REST endpoints with the API Token app enabled and Basic Auth with password enabled | User accesses the endpoint with a regular password | 401 |
API Token REST endpoints (listed in the guide above) | Non sys-admin user is trying to access an API Token app endpoint only intend for sysadmins | 403 |
Please be aware that depending on the system settings, Jira & Confluence might increase the failed login counter up to a point where the user would need to enter a captcha to reset that
counter or let a sys admin do that for him/ her. Until then, every further attempt to access the REST API will result in a 403 Forbidden error.
Read more about the security configuration below:
Jira: https://your-jira/secure/admin/ViewApplicationProperties.jspa - Maximum Authentication Attempts Allowed
Confluence: Atlassian documentation https://confluence.atlassian.com/doc/configuring-captcha-for-failed-logins-216957808.html