API Token AuthenticationAPI Token Authentication
Try For Free

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.

  1. curl -v -u user:password -d '{"tokenDescription":"<enter-your-token-description-here>"}' POST https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

You could also provide an expiration period in month, 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:

  1. curl -v -u user:password -d '{"tokenDescription":"<enter-your-token-description-here>", "tokenValidityTimeInMonths" : 1}' POST https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

Update a token description

  1. curl -v -u user:password -d '{"tokenDescription":"Updated token description"}' -X PATCH https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/<token-id> --header "Content-Type: application/json"

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.

  1. curl -v -u user:password GET https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/ | python -mjson.tool

which produces output like:

  1. [
  2. {
  3. "created": 1573814077364,
  4. "description": "Automation token",
  5. "id": 4,
  6. "lastAccessed": 1573814464012
  7. }
  8. ]

Delete a token 

Grab a token ID retrieved with the previous call and put it to end of the call: 

  1. curl -v -u user:password -X DELETE https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/<token-id>

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 token for other users by providing their user key in the request payload. If no no token validity time is provided, the system default will be automatically assigned. 
How to get a key for a user in Jira/ Confluence is explained in the previous chapter.

  1. curl -v -u admin:passwordOrToken -d '{"tokenDescription":"token for another user", "tokenForUserKey":"JIRAUSER10105"}' POST https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

If a  token validity time is provided, then 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 i.e. 12 month, where only 6 are allowed.

  1. curl -v -u admin:passwordOrToken -d '{"tokenDescription":"token for another user", "tokenForUserKey":"JIRAUSER10105","tokenValidityTimeInMonths":12}' POST https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/token --header "Content-Type: application/json"

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, which is different than the name *.  

  1. curl -v -u admin:password -X DELETE https://<your-jira-or-confluence>/rest/de.resolution.apitokenauth/latest/user/token/deleteAllFor/<user-key-not-user-name>

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

  1. curl -v -u admin:password GET https://<your-jira>/rest/api/2/user?username=some.username | python -mjson.tool
  4. {
  5. "active": true,
  6. "applicationRoles": {
  7. "items": [],
  8. "size": 1
  9. },
  10. "avatarUrls": {
  11. "16x16": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=16",
  12. "24x24": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=24",
  13. "32x32": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=32",
  14. "48x48": "https://www.gravatar.com/avatar/9c7da4947106c84fe2c18c1a48747c54?d=mm&s=48"
  15. },
  16. "displayName": "Some User",
  17. "emailAddress": "some@user.com",
  18. "expand": "groups,applicationRoles",
  19. "groups": {
  20. "items": [],
  21. "size": 1
  22. },
  23. "key": "JIRAUSER10100",
  24. "locale": "en_US",
  25. "name": "Some User",
  26. "self": "https://<your-jira>/rest/api/2/user?username=some.username",
  27. "timeZone": "GMT"
  28. }

Confluence

  1. curl -v -u admin:password GET https://<your-confluence>/rest/api/user?username=some.username | python -mjson.tool
  3. {
  4. "_expandable": {
  5. "status": ""
  6. },
  7. "_links": {
  8. "base": "https://<your-confluence>",
  9. "context": "",
  10. "self": "https://<your-confluence>/rest/api/user?key=e4fc80a46ebbdf4c016fa42e69be01f8"
  11. },
  12. "displayName": "some.username",
  13. "profilePicture": {
  14. "height": 48,
  15. "isDefault": true,
  16. "path": "/images/icons/profilepics/default.svg",
  17. "width": 48
  18. },
  19. "type": "known",
  20. "userKey": "e4fc80a46ebbdf4c016fa42e69be01f8",
  21. "username": "some.username"
  22. }

Filter User Tokens

Since we provide functionality to set a validity time for tokens and before providing more reporting and filter capability via the admin UI in a future version,
admins can use the following REST endpoint to filter for tokens, i.e. to remind users about their tokens soon to expire:

Below examples shows 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


  1. curl -v -u admin:passwordOrToken "https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/tokensByFilter?notValidAfter=1688918956972" | python -mjson.tool

And returns

  1. {
  2. "content": [
  3. {
  4. "created": 1580832062985,
  5. "description": "Shell Script",
  6. "id": 64,
  7. "lastAccessed": 0,
  8. "tokenCreatedByUserKey": "admin",
  9. "tokenForUserKey": "admin",
  10. "validUntil": 1596556862985
  11. },
  12. {
  13. "created": 1580832051168,
  14. "description": "Automation Script",
  15. "id": 63,
  16. "lastAccessed": 0,
  17. "tokenCreatedByUserKey": "admin",
  18. "tokenForUserKey": "admin",
  19. "validUntil": 1612454451168
  20. },
  21. {
  22. "created": 1580892710444,
  23. "description": "API Token from 2020-02-05",
  24. "id": 65,
  25. "lastAccessed": 1580892730216,
  26. "tokenCreatedByUserKey": "admin",
  27. "tokenForUserKey": "admin",
  28. "validUntil": 1612515110443
  29. },
  30. {
  31. "created": 1580893252170,
  32. "description": "token for another user",
  33. "id": 66,
  34. "lastAccessed": 0,
  35. "tokenCreatedByUserKey": "admin",
  36. "tokenForUserKey": "JIRAUSER10105",
  37. "validUntil": 1612515652170
  38. }
  39. ],
  40. "currentPage": 0,
  41. "limit": 50,
  42. "offset": 0,
  43. "paginationLinks": {
  44. "baseUrl": "https://your-jira-or-confluence",
  45. "nextPage": "",
  46. "previousPage": ""
  47. },
  48. "total": 4,
  49. "totalPages": 1
  50. }

The results are paged and you may only retrieve 50 results max per page. Below another example with paging:

  1. curl -v -u admin:passwordOrToken "https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/tokensByFilter?page=0&limit=1&notValidAfter=1688918956972"


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.

  1. {
  2. "content": [
  3. {
  4. "created": 1580832062985,
  5. "description": "Shell Script",
  6. "id": 64,
  7. "lastAccessed": 0,
  8. "tokenCreatedByUserKey": "admin",
  9. "tokenForUserKey": "admin",
  10. "validUntil": 1596556862985
  11. }
  12. ],
  13. "currentPage": 0,
  14. "limit": 1,
  15. "offset": 0,
  16. "paginationLinks": {
  17. "baseUrl": "https://your-jira-or-confluence",
  18. "nextPage": "https://your-jira-or-confluence/rest/de.resolution.apitokenauth/latest/user/tokensByFilter?page=1&limit=1&notValidAfter=1688918956972",
  19. "previousPage": ""
  20. },
  21. "total": 4,
  22. "totalPages": 4
  23. }

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 


This site uses cookies to deliver its service & to analyse traffic. By browsing this site, you accept the privacy policy.

Our Wiki uses cookies

We want to give you the best possible experience on our website. For this we use technically required cookies and, if you agree, cookies for analysis and marketing purposes. You can find more information about the cookies in our Privacy Policy. By tapping ‘Accept All,’ you consent to the use of these methods by us and third parties.

Necessary
Always Active
Analytics
Advertisement
Other